librus-python-api 1.0.0rc1__py3-none-any.whl → 1.0.1__py3-none-any.whl

librus_python_api/__init__.py

@@ -120,7 +120,7 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.0.0rc1"
+__version__ = "1.0.1"
 
 __all__ = [
     "AccountContext",

librus_python_api/_notification_bootstrap.py

@@ -0,0 +1,124 @@
+"""Original bounded validation of caller-established, neutral offline mappings."""
+
+from dataclasses import asdict
+
+from librus_python_api._notification_codec import (
+    HEX,
+    canonical_notification_id,
+    dump,
+    validate_historical_item,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import NotificationCategory, RecentScheduleEvent
+from librus_python_api.notification_models import (
+    NotificationBaselineMapping,
+    NotificationBootstrap,
+    NotificationItem,
+    NotificationProvenance,
+    NotificationSeen,
+    NotificationState,
+)
+
+
+def prepare_bootstrap(
+    plan: NotificationBootstrap, per_category: int, batch_items: int, batch_bytes: int
+) -> tuple[
+    NotificationState,
+    tuple[NotificationItem, ...],
+    tuple[NotificationBaselineMapping, ...],
+]:
+    if type(plan.mappings) is not tuple or type(plan.pending_events) is not tuple:
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    if (
+        len(plan.mappings) > len(NotificationCategory) * per_category
+        or len(plan.pending_events) > batch_items
+    ):
+        raise LibrusError(ErrorKind.LIMIT)
+    seen, unmapped = _mapped_state(plan.mappings, per_category)
+    items: list[NotificationItem] = []
+    used = 2
+    agenda_ids = set(
+        next(
+            entry.identifiers
+            for entry in seen
+            if entry.category is NotificationCategory.AGENDA
+        )
+    )
+    for event in plan.pending_events:
+        if type(event) is not RecentScheduleEvent:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        item = NotificationItem(
+            NotificationCategory.AGENDA,
+            "0" * 64,
+            event,
+            None,
+            None,
+            NotificationProvenance.IMPORTED_HISTORY,
+        )
+        try:
+            validate_historical_item(item)
+        except LibrusError:
+            raise LibrusError(ErrorKind.INVALID_INPUT) from None
+        identifier = canonical_notification_id(NotificationCategory.AGENDA, event)
+        if identifier in agenda_ids:
+            # A conflict cannot silently consume an externally pending event.
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        agenda_ids.add(identifier)
+        final = NotificationItem(
+            item.category, identifier, event, None, None, item.provenance
+        )
+        used += len(
+            dump({"kind": "RecentScheduleEvent", "item": asdict(final)}, batch_bytes)
+        ) + bool(items)
+        if used > batch_bytes:
+            raise LibrusError(ErrorKind.LIMIT)
+        items.append(final)
+    if len(agenda_ids) > per_category:
+        raise LibrusError(ErrorKind.LIMIT)
+    return NotificationState(True, seen), tuple(items), unmapped
+
+
+def _mapped_state(
+    mappings: tuple[NotificationBaselineMapping, ...], per_category: int
+) -> tuple[tuple[NotificationSeen, ...], tuple[NotificationBaselineMapping, ...]]:
+    seen: dict[NotificationCategory, list[str]] = {
+        category: [] for category in NotificationCategory
+    }
+    sources: set[tuple[NotificationCategory, str]] = set()
+    native: set[tuple[NotificationCategory, str]] = set()
+    unmapped = []
+    counts = {category: 0 for category in NotificationCategory}
+    for mapping in mappings:
+        if (
+            type(mapping) is not NotificationBaselineMapping
+            or not isinstance(mapping.category, NotificationCategory)
+            or type(mapping.source_identifier) is not str
+            or not 1 <= len(mapping.source_identifier) <= 256
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        try:
+            mapping.source_identifier.encode("utf-8")
+        except UnicodeError:
+            raise LibrusError(ErrorKind.INVALID_INPUT) from None
+        source = (mapping.category, mapping.source_identifier)
+        if source in sources:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        sources.add(source)
+        counts[mapping.category] += 1
+        if counts[mapping.category] > per_category:
+            raise LibrusError(ErrorKind.LIMIT)
+        identifier = mapping.native_identifier
+        if identifier is None:
+            unmapped.append(mapping)
+            continue
+        if type(identifier) is not str or HEX.fullmatch(identifier) is None:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        key = (mapping.category, identifier)
+        if key in native:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        native.add(key)
+        seen[mapping.category].append(identifier)
+    return tuple(
+        NotificationSeen(category, tuple(identifiers))
+        for category, identifiers in seen.items()
+    ), tuple(unmapped)

librus_python_api/_notification_codec.py

@@ -10,6 +10,7 @@ from typing import Any, cast
 
 from pydantic import TypeAdapter, ValidationError
 
+from librus_python_api.config import SCHOOL_MAX_CONTENT_LENGTH, SCHOOL_MAX_FIELD_LENGTH
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.models import (
     Announcement,
@@ -18,6 +19,8 @@ from librus_python_api.models import (
     HomeworkItem,
     Identity,
     MessageSummary,
+    MessagingBackend,
+    ModernMessageSummary,
     NotificationCategory,
     NumericGrade,
     Observation,
@@ -28,6 +31,7 @@ from librus_python_api.models import (
 from librus_python_api.notification_models import (
     NotificationBatch,
     NotificationItem,
+    NotificationProvenance,
     NotificationSeen,
     NotificationState,
     NotificationValue,
@@ -45,6 +49,7 @@ _VALUE_TYPES: dict[str, type[Any]] = {
         DescriptiveGrade,
         AttendanceRecord,
         MessageSummary,
+        ModernMessageSummary,
         Announcement,
         HomeworkItem,
         RecentScheduleEvent,
@@ -53,7 +58,7 @@ _VALUE_TYPES: dict[str, type[Any]] = {
 _CATEGORY_TYPES: dict[NotificationCategory, tuple[type[Any], ...]] = {
     NotificationCategory.GRADES: (NumericGrade, DescriptiveGrade),
     NotificationCategory.ATTENDANCE: (AttendanceRecord,),
-    NotificationCategory.MESSAGES: (MessageSummary,),
+    NotificationCategory.MESSAGES: (MessageSummary, ModernMessageSummary),
     NotificationCategory.ANNOUNCEMENTS: (Announcement,),
     NotificationCategory.HOMEWORK: (HomeworkItem,),
     NotificationCategory.AGENDA: (RecentScheduleEvent,),
@@ -144,6 +149,14 @@ def canonical_notification_id(
     if isinstance(value, RecentScheduleEvent):
         # Independently specified three-field canonical identity, including data.
         canonical: Any = asdict(value)
+    elif isinstance(value, ModernMessageSummary):
+        canonical = [
+            2,
+            category.value,
+            MessagingBackend.MODERN.value,
+            value.reference.folder.value,
+            value.reference.identifier,
+        ]
     elif isinstance(value, MessageSummary):
         canonical = [
             1,
@@ -248,12 +261,17 @@ def encode_batch(batch: NotificationBatch, maximum: int) -> bytes:
 
 def restore_batch(payload: bytes, maximum: int) -> NotificationBatch:
     record = load(payload, maximum)
+    if type(record) is dict and "messages_backend" not in record:
+        # Existing format-3 deliveries could only contain legacy summaries.
+        record["messages_backend"] = MessagingBackend.LEGACY.value
     if (
         type(record) is not dict
         or set(record) != {f.name for f in fields(NotificationBatch)}
         or type(record["items"]) is not list
     ):
         raise LibrusError(ErrorKind.PARSE)
+    if len(record["items"]) > 4096:
+        raise LibrusError(ErrorKind.LIMIT)
     items = []
     for entry in record["items"]:
         if (
@@ -264,6 +282,8 @@ def restore_batch(payload: bytes, maximum: int) -> NotificationBatch:
         ):
             raise LibrusError(ErrorKind.PARSE)
         item = entry["item"]
+        if type(item) is dict and "provenance" not in item:
+            item["provenance"] = NotificationProvenance.OBSERVED.value
         if type(item) is not dict or set(item) != {
             f.name for f in fields(NotificationItem)
         }:
@@ -282,10 +302,26 @@ def restore_batch(payload: bytes, maximum: int) -> NotificationBatch:
                 value,
                 parsed.identity,
                 parsed.observation,
+                parsed.provenance,
             )
         )
     record["items"] = []
     batch = typed(NotificationBatch, record, maximum)
+    _validate_batch_items(batch, items)
+    return NotificationBatch(
+        batch.receipt,
+        batch.context,
+        batch.first_run,
+        batch.categories,
+        tuple(items),
+        batch.has_more_schedule,
+        batch.messages_backend,
+    )
+
+
+def _validate_batch_items(
+    batch: NotificationBatch, items: list[NotificationItem]
+) -> None:
     if (
         HEX.fullmatch(batch.receipt) is None
         or HEX.fullmatch(batch.context.identifier) is None
@@ -293,18 +329,68 @@ def restore_batch(payload: bytes, maximum: int) -> NotificationBatch:
         or len(set(batch.categories)) != len(batch.categories)
     ):
         raise LibrusError(ErrorKind.PARSE)
+    for item in items:
+        if item.category not in batch.categories:
+            raise LibrusError(ErrorKind.PARSE)
+        if item.provenance is NotificationProvenance.IMPORTED_HISTORY:
+            validate_historical_item(item)
+            if (
+                batch.categories != (NotificationCategory.AGENDA,)
+                or batch.first_run
+                or batch.has_more_schedule
+            ):
+                raise LibrusError(ErrorKind.PARSE)
+        elif (
+            item.identity is None
+            or item.observation is None
+            or item.observation.account != batch.context.alias
+            or item.identity.observation.account != batch.context.alias
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        if isinstance(item.value, (MessageSummary, ModernMessageSummary)):
+            expected = (
+                MessagingBackend.MODERN
+                if isinstance(item.value, ModernMessageSummary)
+                else MessagingBackend.LEGACY
+            )
+            if (
+                batch.messages_backend is not expected
+                or item.value.reference.account != batch.context.alias
+            ):
+                raise LibrusError(ErrorKind.PARSE)
     if any(
-        item.category not in batch.categories
-        or item.observation.account != batch.context.alias
-        or item.identity.observation.account != batch.context.alias
-        for item in items
-    ):
+        item.provenance is NotificationProvenance.IMPORTED_HISTORY for item in items
+    ) and not is_historical_batch(batch, items):
         raise LibrusError(ErrorKind.PARSE)
-    return NotificationBatch(
-        batch.receipt,
-        batch.context,
-        batch.first_run,
-        batch.categories,
-        tuple(items),
-        batch.has_more_schedule,
+
+
+def is_historical_batch(
+    batch: NotificationBatch, items: list[NotificationItem] | None = None
+) -> bool:
+    values = batch.items if items is None else items
+    return bool(values) and all(
+        item.provenance is NotificationProvenance.IMPORTED_HISTORY for item in values
     )
+
+
+def validate_historical_item(item: NotificationItem) -> None:
+    if (
+        item.category is not NotificationCategory.AGENDA
+        or type(item.value) is not RecentScheduleEvent
+        or item.identity is not None
+        or item.observation is not None
+        or item.provenance is not NotificationProvenance.IMPORTED_HISTORY
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    value = item.value
+    for text, minimum, maximum in (
+        (value.date_added, 1, SCHOOL_MAX_FIELD_LENGTH),
+        (value.type, 1, SCHOOL_MAX_FIELD_LENGTH),
+        (value.data, 0, SCHOOL_MAX_CONTENT_LENGTH),
+    ):
+        if type(text) is not str or not minimum <= len(text) <= maximum:
+            raise LibrusError(ErrorKind.PARSE)
+        try:
+            text.encode("utf-8")
+        except UnicodeError:
+            raise LibrusError(ErrorKind.PARSE) from None

librus_python_api/_storage.py

@@ -8,10 +8,11 @@ import os
 import secrets
 import sqlite3
 import stat
+import sys
 from collections.abc import Callable, Coroutine, Iterator
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self
 
 from pydantic import Field
 
@@ -19,10 +20,16 @@ from librus_python_api.config import _ValidatedConfig
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.lifecycle import join_owned
 
+if TYPE_CHECKING:
+    from librus_python_api._windows_filesystem import WindowsDirectory
+
 
 class _StorageLimits(_ValidatedConfig):
     operations: int = Field(default=8, ge=1, le=64)
-    busy_timeout_seconds: float = Field(default=0.1, gt=0, le=5, allow_inf_nan=False)
+    # Several local processes (one per agent host session) commonly share one
+    # store. Each transaction is short, but FULL synchronous commits can exceed
+    # 100 ms on slow disks, so ordinary operations wait up to one second.
+    busy_timeout_seconds: float = Field(default=1.0, gt=0, le=5, allow_inf_nan=False)
     # Final saves follow upstream side effects (a dispatched send or a consumed
     # read-once page), so they wait longer for other contexts' write locks.
     final_busy_timeout_seconds: float = Field(
@@ -60,6 +67,7 @@ class _SQLiteStore:
         self._close_task: asyncio.Task[None] | None = None
         self._file_identity: tuple[int, int] | None = None
         self._context_salt: bytes | None = None
+        self._windows_directory: WindowsDirectory | None = None
 
     def context_identifier(self, context: str) -> str:
         """Store-local context pseudonym; requires an explicitly opened store."""
@@ -87,7 +95,7 @@ class _SQLiteStore:
         await self.aclose()
 
     async def open(self) -> None:
-        if os.name != "posix":
+        if os.name != "posix" and sys.platform != "win32":
             raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
         if self._opened or self._opening or self._closing or self._closed:
             raise LibrusError(ErrorKind.INVALID_INPUT)
@@ -97,6 +105,9 @@ class _SQLiteStore:
             self._opened = True
         finally:
             self._opening = False
+            if not self._opened and self._windows_directory is not None:
+                self._windows_directory.close()
+                self._windows_directory = None
 
     async def aclose(self) -> None:
         if (
@@ -123,6 +134,13 @@ class _SQLiteStore:
             task.cancel()
         for task in tasks:
             await join_owned(task)
+        if self._windows_directory is not None:
+            try:
+                self._windows_directory.close()
+            except OSError:
+                raise LibrusError(ErrorKind.STORAGE) from None
+            finally:
+                self._windows_directory = None
         self._closed = True
         self._opened = False
 
@@ -207,6 +225,14 @@ class _SQLiteStore:
     def _check_directory(self) -> None:
         # A private immediate parent is the trust boundary. Malicious same-user
         # filesystem writers and unsuitable network filesystems are not isolated.
+        if sys.platform == "win32":
+            from librus_python_api._windows_filesystem import WindowsDirectory
+
+            if self._windows_directory is None:
+                self._windows_directory = WindowsDirectory(self._directory, create=True)
+            else:
+                self._windows_directory.validate()
+            return
         if self._directory.is_symlink():
             raise LibrusError(ErrorKind.STORAGE)
         self._directory.mkdir(mode=0o700, exist_ok=True)
@@ -219,6 +245,14 @@ class _SQLiteStore:
             raise LibrusError(ErrorKind.STORAGE)
 
     def _check_file(self, *, create: bool = False) -> None:
+        if self._windows_directory is not None:
+            identity = self._windows_directory.check_file(
+                self._filename, self._database_bytes, create=create
+            )
+            if self._file_identity is not None and identity != self._file_identity:
+                raise LibrusError(ErrorKind.STORAGE)
+            self._file_identity = identity
+            return
         if self._path.is_symlink():
             raise LibrusError(ErrorKind.STORAGE)
         flags = os.O_RDWR | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
@@ -246,6 +280,11 @@ class _SQLiteStore:
 
     def _check_sidecars(self) -> None:
         for suffix in ("-journal", "-wal", "-shm"):
+            if self._windows_directory is not None:
+                self._windows_directory.check_sidecar(
+                    self._filename + suffix, self._database_bytes + 1024 * 1024
+                )
+                continue
             path = self._path.with_name(self._path.name + suffix)
             try:
                 status = path.lstat()