librus-python-api 1.0.0rc1__py3-none-any.whl

librus_python_api/notification_workflow.py

@@ -0,0 +1,303 @@
+"""Optional native category orchestration with durable at-least-once replay."""
+
+import secrets
+from dataclasses import asdict
+from datetime import date, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+from librus_python_api._notification_codec import (
+    META_BYTES,
+    canonical_notification_id,
+    dump,
+    encode_batch,
+)
+from librus_python_api.budget import RequestBudget
+from librus_python_api.checkpoint import validate_checkpoint
+from librus_python_api.config import homework_form
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    AttendanceView,
+    GradeView,
+    MessageFolder,
+    NotificationCategory,
+    ScheduleEventResponse,
+    ScheduleEvents,
+)
+from librus_python_api.notification_models import (
+    NotificationBatch,
+    NotificationItem,
+    NotificationState,
+    NotificationValue,
+)
+from librus_python_api.notification_persistence import NotificationStore
+from librus_python_api.service import AccountClient
+
+
+class NotificationWorkflow:
+    """Explicit selected-category poll and acknowledgement, without MCP schemas.
+
+    A pending batch is returned without network until explicitly acknowledged.
+    Replay of raw schedule bytes requires no fresh consume consent. New read-once
+    retrieval requires allow_consume_events=True every time; no hidden retry.
+    """
+
+    def __init__(self, client: AccountClient, store: NotificationStore) -> None:
+        if not isinstance(client, AccountClient) or not isinstance(
+            store, NotificationStore
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self.client, self.store = client, store
+
+    async def poll(
+        self,
+        *,
+        categories: tuple[NotificationCategory, ...],
+        allow_consume_events: bool = False,
+        homework_window: tuple[date, date] | None = None,
+        checkpoint_timeout_seconds: float = 5.0,
+        budget: RequestBudget | None = None,
+    ) -> NotificationBatch:
+        if (
+            type(categories) is not tuple
+            or not 1 <= len(categories) <= 6
+            or any(
+                not isinstance(category, NotificationCategory)
+                for category in categories
+            )
+            or len(set(categories)) != len(categories)
+            or type(allow_consume_events) is not bool
+            or (budget is not None and not isinstance(budget, RequestBudget))
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        validate_checkpoint(self.store._checkpoint, checkpoint_timeout_seconds)
+        if homework_window is None:
+            today = datetime.now(ZoneInfo("Europe/Warsaw")).date()
+            homework_window = (today - timedelta(days=7), today)
+        if type(homework_window) is not tuple or len(homework_window) != 2:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        homework_form(*homework_window)
+        actual = budget if budget is not None else self.client._service._budget()
+        actual._bind_loop()
+        actual.remaining_seconds()
+        window = homework_window
+        return await self.store._transaction(
+            self.client.context,
+            lambda: self._poll(
+                categories,
+                allow_consume_events,
+                window,
+                checkpoint_timeout_seconds,
+                actual,
+            ),
+        )
+
+    async def acknowledge(self, receipt: str) -> None:
+        await self.store.acknowledge(receipt, context=self.client.context)
+
+    async def _poll(
+        self,
+        categories: tuple[NotificationCategory, ...],
+        consume: bool,
+        window: tuple[date, date],
+        seconds: float,
+        budget: RequestBudget,
+    ) -> NotificationBatch:
+        context, store = self.client.context, self.store
+        pending, raw, uncertain = await store._io(lambda: store._pending(context))
+        if pending is not None:
+            if pending.categories != categories:
+                raise LibrusError(ErrorKind.INVALID_INPUT)
+            return pending
+        agenda = NotificationCategory.AGENDA in categories
+        if agenda and raw is None:
+            if uncertain:
+                raise LibrusError(ErrorKind.CHECKPOINT)
+            if not consume:
+                raise LibrusError(ErrorKind.INVALID_INPUT)
+        state = await store._io(lambda: store._read_state(context.identifier))
+        ordinary = await self._ordinary(categories, window, budget)
+        # Validate whole ordinary results and state capacity before consuming.
+        items = self._new_items(ordinary, state)
+        if len(items) > store.limits.batch_items:
+            raise LibrusError(ErrorKind.LIMIT)
+        for entry in state.seen:
+            if (
+                len(entry.identifiers)
+                + sum(item.category == entry.category for item in items)
+                > store.limits.seen_ids_per_category
+            ):
+                raise LibrusError(ErrorKind.LIMIT)
+        provisional = NotificationBatch(
+            "0" * 64, context, not state.initialized, categories, items, False
+        )
+        encode_batch(provisional, store.limits.batch_bytes)
+        events: ScheduleEvents | None = None
+        if agenda and raw is None:
+            reserve = min(
+                self.client._service._transport_limits.response_max_bytes,
+                budget.remaining_response_bytes,
+            )
+            await store._io(lambda: store._reserve(context.identifier, reserve))
+
+            async def persist(response: ScheduleEventResponse) -> None:
+                await store._io(
+                    lambda: store._checkpoint(context, response), finishing=True
+                )
+
+            events = await self.client.consume_schedule_events(
+                checkpoint=persist,
+                allow_consume_events=True,
+                checkpoint_timeout_seconds=seconds,
+                budget=budget,
+            )
+            _, raw, uncertain = await store._io(lambda: store._pending(context))
+            assert raw is not None and not uncertain
+        raw_identifier: str | None = None
+        cursor: int | None = None
+        total: int | None = None
+        more = False
+        if agenda:
+            assert raw is not None
+            if events is None:
+                events = await self.client.decode_schedule_events(raw[1], budget=budget)
+            if raw[3] is not None and raw[3] != len(events.items):
+                raise LibrusError(ErrorKind.PARSE)
+            schedule, cursor = self._slice_schedule(
+                events, raw[2], state, store.limits.batch_items - len(items)
+            )
+            items += schedule
+            raw_identifier, total = raw[0], len(events.items)
+            more = cursor < total
+        batch = NotificationBatch(
+            secrets.token_hex(32),
+            context,
+            not state.initialized,
+            categories,
+            items,
+            more,
+        )
+        await store._io(
+            lambda: store._stage(batch, raw_identifier, cursor, total), finishing=True
+        )
+        return batch
+
+    async def _ordinary(
+        self,
+        categories: tuple[NotificationCategory, ...],
+        window: tuple[date, date],
+        budget: RequestBudget,
+    ) -> tuple[NotificationItem, ...]:
+        items = []
+        for category in categories:
+            values: tuple[NotificationValue, ...]
+            if category is NotificationCategory.AGENDA:
+                continue
+            if category is NotificationCategory.GRADES:
+                grades = await self.client.grades(
+                    view=GradeView.LAST_LOGIN, budget=budget
+                )
+                values = (*grades.records.numeric, *grades.records.descriptive)
+                identity, observation = grades.identity, grades.observation
+            elif category is NotificationCategory.ATTENDANCE:
+                attendance = await self.client.attendance(
+                    view=AttendanceView.LAST_LOGIN, budget=budget
+                )
+                values, identity, observation = (
+                    attendance.items,
+                    attendance.identity,
+                    attendance.observation,
+                )
+            elif category is NotificationCategory.MESSAGES:
+                messages = await self.client.messages_page(
+                    MessageFolder.RECEIVED, budget=budget
+                )
+                values, identity, observation = (
+                    messages.items,
+                    messages.identity,
+                    messages.observation,
+                )
+            elif category is NotificationCategory.ANNOUNCEMENTS:
+                announcements = await self.client.announcements(budget=budget)
+                values, identity, observation = (
+                    announcements.items,
+                    announcements.identity,
+                    announcements.observation,
+                )
+            else:
+                assert category is NotificationCategory.HOMEWORK
+                homework = await self.client.homework(*window, budget=budget)
+                values, identity, observation = (
+                    homework.items,
+                    homework.identity,
+                    homework.observation,
+                )
+            for value in values:
+                items.append(
+                    NotificationItem(
+                        category,
+                        canonical_notification_id(category, value),
+                        value,
+                        identity,
+                        observation,
+                    )
+                )
+        return tuple(items)
+
+    @staticmethod
+    def _new_items(
+        items: tuple[NotificationItem, ...], state: NotificationState
+    ) -> tuple[NotificationItem, ...]:
+        seen = {entry.category: set(entry.identifiers) for entry in state.seen}
+        result = []
+        for item in items:
+            if item.identifier not in seen[item.category]:
+                result.append(item)
+                seen[item.category].add(item.identifier)
+        return tuple(result)
+
+    def _slice_schedule(
+        self,
+        events: ScheduleEvents,
+        cursor: int,
+        state: NotificationState,
+        available: int,
+    ) -> tuple[tuple[NotificationItem, ...], int]:
+        if not 0 <= cursor <= len(events.items):
+            raise LibrusError(ErrorKind.PARSE)
+        seen = {
+            identifier
+            for entry in state.seen
+            if entry.category is NotificationCategory.AGENDA
+            for identifier in entry.identifiers
+        }
+        items: list[NotificationItem] = []
+        used = 2
+        for index in range(cursor, len(events.items)):
+            value = events.items[index]
+            identifier = canonical_notification_id(NotificationCategory.AGENDA, value)
+            if identifier in seen:
+                cursor = index + 1
+                continue
+            if len(items) >= min(self.store.limits.replay_events, available):
+                break
+            encoded = dump(asdict(value), META_BYTES)
+            size = used + len(encoded) + bool(items)
+            if size > self.store.limits.replay_bytes:
+                if not items:
+                    raise LibrusError(ErrorKind.LIMIT)
+                break
+            items.append(
+                NotificationItem(
+                    NotificationCategory.AGENDA,
+                    identifier,
+                    value,
+                    events.identity,
+                    events.observation,
+                )
+            )
+            seen.add(identifier)
+            used = size
+            cursor = index + 1
+        if not items and cursor < len(events.items):
+            raise LibrusError(ErrorKind.LIMIT)
+        return tuple(items), cursor

librus_python_api/notifications.py

@@ -0,0 +1,216 @@
+"""Original bounded count/event parsers; no seen state, hashing or persistence."""
+
+import re
+import zlib
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    NOTIFICATION_DESTINATIONS,
+    NOTIFICATION_MAX_COUNT,
+    NOTIFICATION_MAX_MENU_ITEMS,
+    SCHEDULE_EMPTY_LABEL,
+    SCHEDULE_EVENT_HEADERS,
+    SCHEDULE_MAX_EVENTS,
+    SCHEDULE_RESPONSE_VERSION,
+    SCHOOL_MAX_CONTENT_LENGTH,
+    SCHOOL_MAX_FIELD_LENGTH,
+    SCHOOL_MAX_TOTAL_TEXT_LENGTH,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    Identity,
+    NotificationCategory,
+    NotificationCount,
+    Observation,
+    Person,
+    RecentScheduleEvent,
+    ScheduleEventResponse,
+    ScheduleEventWire,
+)
+from librus_python_api.parsers import parse_page
+
+
+def parse_notification_counts(body: bytes) -> tuple[NotificationCount, ...]:
+    root = parse_page(body)
+    menus = root.xpath("//div[@id='graphic-menu']/ul")
+    if len(menus) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    rows = menus[0].xpath("./li")
+    if len(rows) > NOTIFICATION_MAX_MENU_ITEMS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items = []
+    seen = set()
+    for row in rows:
+        links = row.xpath("./a")
+        if len(links) > 4:
+            raise LibrusError(ErrorKind.LIMIT)
+        known = [
+            a
+            for a in links
+            if a.get("href") in NOTIFICATION_DESTINATIONS
+            and "counter" not in a.get("class", "").split()
+        ]
+        if not known:
+            continue
+        if len(known) != 1:
+            raise LibrusError(ErrorKind.PARSE)
+        category = NotificationCategory(NOTIFICATION_DESTINATIONS[known[0].get("href")])
+        if category in seen:
+            raise LibrusError(ErrorKind.PARSE)
+        seen.add(category)
+        counters = [a for a in links if "counter" in a.get("class", "").split()]
+        marked = [
+            e
+            for e in row.iterdescendants()
+            if isinstance(e.tag, str) and "counter" in e.get("class", "").split()
+        ]
+        if len(marked) != len(counters):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if len(counters) > 1:
+            raise LibrusError(ErrorKind.PARSE)
+        count = 0
+        if counters:
+            value = markup.text(counters[0], 16)
+            if re.fullmatch(r"[0-9]{1,7}", value) is None:
+                raise LibrusError(ErrorKind.PARSE)
+            count = int(value)
+            if count > NOTIFICATION_MAX_COUNT:
+                raise LibrusError(ErrorKind.LIMIT)
+        label = markup.text(known[0], SCHOOL_MAX_FIELD_LENGTH)
+        if not label:
+            raise LibrusError(ErrorKind.PARSE)
+        items.append(NotificationCount(category, label, count))
+    if not items:
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(items)
+
+
+def parse_schedule_events(body: bytes) -> tuple[RecentScheduleEvent, ...]:
+    root = parse_page(body)
+    containers = root.xpath(
+        "//div[contains(concat(' ',normalize-space(@class),' '),"
+        "' container-background ')]"
+    )
+    if len(containers) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    tables = containers[0].xpath(".//table")
+    empty = containers[0].xpath(".//p[@class='msgEmptyTable']")
+    if tables and empty:
+        raise LibrusError(ErrorKind.PARSE)
+    if len(tables) != 1:
+        empty = containers[0].xpath("./p[@class='msgEmptyTable']")
+        if (
+            not tables
+            and len(empty) == 1
+            and markup.text(empty[0]) == SCHEDULE_EMPTY_LABEL
+        ):
+            return ()
+        raise LibrusError(ErrorKind.PARSE)
+    rows = list(markup.rows(tables[0]))
+    if len(rows) > SCHEDULE_MAX_EVENTS + 1:
+        raise LibrusError(ErrorKind.LIMIT)
+    header = markup.cells(rows[0]) if rows else []
+    if (
+        not rows
+        or any(markup.colspan(c) != 1 for c in header)
+        or tuple(markup.text(c).casefold() for c in header) != SCHEDULE_EVENT_HEADERS
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    items = []
+    total = 0
+    for row in rows[1:]:
+        cells = markup.cells(row)
+        if (
+            len(cells) != 4
+            or any(c.tag != "td" or markup.colspan(c) != 1 for c in cells)
+            or markup.in_header(row)
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        # Display row numbers are not durable identities.
+        values = [markup.text(c, SCHOOL_MAX_FIELD_LENGTH) for c in cells[:3]]
+        if tuple(value.casefold() for value in values) == SCHEDULE_EVENT_HEADERS[:3]:
+            raise LibrusError(ErrorKind.PARSE)
+        data = markup.text(cells[3], SCHOOL_MAX_CONTENT_LENGTH, multiline=True)
+        if not values[1] or not values[2]:
+            raise LibrusError(ErrorKind.PARSE)
+        total += sum(map(len, values)) + len(data)
+        if total > SCHOOL_MAX_TOTAL_TEXT_LENGTH:
+            raise LibrusError(ErrorKind.LIMIT)
+        items.append(RecentScheduleEvent(values[1], values[2], data))
+    return tuple(items)
+
+
+def validate_response(
+    response: ScheduleEventResponse, account: str, wire_limit: int
+) -> None:
+    if (
+        not isinstance(response, ScheduleEventResponse)
+        or type(response.version) is not int
+        or response.version != SCHEDULE_RESPONSE_VERSION
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    wire = response.wire
+    if (
+        not isinstance(wire, ScheduleEventWire)
+        or type(wire.body) is not bytes
+        or len(wire.body) > wire_limit
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    if (
+        not isinstance(response.identity, Identity)
+        or not isinstance(response.identity.observation, Observation)
+        or not isinstance(response.identity.owner, Person)
+        or not isinstance(response.identity.student, Person)
+        or not isinstance(response.observation, Observation)
+        or response.observation.account != account
+        or response.identity.observation.account != account
+        or response.observation.source != "consume_schedule_events"
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    for values in (wire.content_codings, wire.transfer_codings):
+        if (
+            type(values) is not tuple
+            or len(values) > 128
+            or any(type(v) is not str or len(v) > 8192 for v in values)
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+    if wire.content_type is not None and (
+        type(wire.content_type) is not str or len(wire.content_type) > 8192
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+
+
+def decode_payload(body: bytes, wire: ScheduleEventWire, limit: int) -> bytes:
+    if (wire.content_type or "").split(";", 1)[0].strip().casefold() != "text/html":
+        raise LibrusError(ErrorKind.PARSE)
+    if (
+        len(wire.content_codings) > 1
+        or any(
+            v.strip().casefold() not in ("identity", "gzip")
+            for v in wire.content_codings
+        )
+        or len(wire.transfer_codings) > 1
+        or any(v.strip().casefold() != "chunked" for v in wire.transfer_codings)
+    ):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    if (
+        not wire.content_codings
+        or wire.content_codings[0].strip().casefold() == "identity"
+    ):
+        if len(body) > limit:
+            raise LibrusError(ErrorKind.LIMIT)
+        return body
+    failed = False
+    decoded = b""
+    try:
+        inflater = zlib.decompressobj(16 + zlib.MAX_WBITS)
+        decoded = inflater.decompress(body, limit + 1)
+        if len(decoded) > limit:
+            raise LibrusError(ErrorKind.LIMIT)
+        if not inflater.eof or inflater.unused_data:
+            failed = True
+    except zlib.error:
+        failed = True
+    if failed:
+        raise LibrusError(ErrorKind.PARSE)
+    return decoded