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

librus_python_api/recipients.py

@@ -0,0 +1,271 @@
+"""Independent bounded named-group and ID-bearing recipient parsing."""
+
+import re
+
+from lxml import html
+
+from librus_python_api.config import (
+    MESSAGE_INFORMATION_NOTICES,
+    RECIPIENT_CLASS_UNAVAILABLE_NOTICE,
+    RECIPIENT_GROUP_TYPE_PATTERN,
+    RECIPIENT_MAX_GROUPS,
+    RECIPIENT_MAX_ITEMS,
+    RECIPIENT_MAX_LABEL_LENGTH,
+    RECIPIENT_MAX_TOTAL_TEXT_LENGTH,
+    RECIPIENT_SELECTION_PROMPT,
+    RECIPIENT_UNSUPPORTED_TYPES,
+    recipient_form,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.markup import rows, text
+from librus_python_api.models import (
+    Recipient,
+    RecipientGroup,
+    RecipientGroupChoice,
+    RecipientGroupReference,
+    RecipientReference,
+)
+from librus_python_api.parsers import page_notices, parse_page
+
+
+def validate_group(
+    reference: RecipientGroupReference, account: str, *, choices: bool = False
+) -> None:
+    if (
+        not isinstance(reference, RecipientGroupReference)
+        or reference.account != account
+        or type(reference.identifier) is not str
+        or RECIPIENT_GROUP_TYPE_PATTERN.fullmatch(reference.identifier) is None
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    recipient_form(reference.identifier, selection_id=reference.selection_id)
+    if choices and (reference.identifier != "grupa" or reference.selection_id != "0"):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    if (
+        not choices
+        and reference.identifier in RECIPIENT_UNSUPPORTED_TYPES
+        and reference.selection_id == "0"
+    ):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _unavailable(document: html.HtmlElement) -> None:
+    # Localized UI text is a capability failure, not proof of zero recipients.
+    for marker in document.xpath('//p[@class="msgEmptyTable"]'):
+        if text(marker) == RECIPIENT_CLASS_UNAVAILABLE_NOTICE:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _recipient_document(body: bytes) -> html.HtmlElement:
+    document = parse_page(body)
+    _unavailable(document)
+    if any(n not in MESSAGE_INFORMATION_NOTICES for n in page_notices(document)):
+        raise LibrusError(ErrorKind.PARSE)
+    return document
+
+
+def parse_recipient_group_choices(
+    body: bytes, group: RecipientGroupReference
+) -> tuple[RecipientGroupChoice, ...]:
+    validate_group(group, group.account, choices=True)
+    document = _recipient_document(body)
+    selectors = document.xpath('//select[@name="idGrupy" and @id="idGrupy"]')
+    if (
+        len(selectors) != 1
+        or len(document.xpath("//select")) != 1
+        or document.xpath('//label|//input[@type="checkbox"]')
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    markers = document.xpath('//p[@class="msgEmptyTable"]')
+    if len(markers) != 1 or text(markers[0]) != RECIPIENT_SELECTION_PROMPT:
+        raise LibrusError(ErrorKind.PARSE)
+    options = list(selectors[0])
+    if not options or len(options) > RECIPIENT_MAX_ITEMS + 1:
+        raise LibrusError(ErrorKind.LIMIT if options else ErrorKind.PARSE)
+    result = []
+    seen = set()
+    total = 0
+    for option in options:
+        if option.tag != "option":
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        identifier = option.get("value", "")
+        if re.fullmatch(r"0|[1-9][0-9]{0,63}", identifier) is None:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if identifier in seen:
+            raise LibrusError(ErrorKind.PARSE)
+        seen.add(identifier)
+        label = text(option, RECIPIENT_MAX_LABEL_LENGTH)
+        if identifier == "0":
+            if label:
+                raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+            continue
+        if not label:
+            raise LibrusError(ErrorKind.PARSE)
+        total += len(label)
+        if total > RECIPIENT_MAX_TOTAL_TEXT_LENGTH:
+            raise LibrusError(ErrorKind.LIMIT)
+        result.append(
+            RecipientGroupChoice(
+                RecipientGroupReference("grupa", group.account, identifier),
+                label,
+                option.get("disabled") is None and selectors[0].get("disabled") is None,
+            )
+        )
+    if "0" not in seen:
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(result)
+
+
+def parse_recipient_groups(body: bytes, account: str) -> tuple[RecipientGroup, ...]:
+    document = _recipient_document(body)
+    tables = document.xpath(
+        '//table[contains(concat(" ",normalize-space(@class)," "),'
+        '" message-recipients ")]'
+    )
+    if len(tables) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    result: list[RecipientGroup] = []
+    seen: set[str] = set()
+    for row in rows(tables[0]):
+        parent = row.getparent()
+        if parent is None or parent.tag != "tbody":
+            continue
+        inputs = row.xpath(
+            './/input[contains(concat(" ",normalize-space(@class)," "),'
+            '" recipiantTypeRadio ")]'
+        )
+        if len(inputs) != 1:
+            raise LibrusError(ErrorKind.PARSE)
+        radio = inputs[0]
+        identifier = radio.get("value", "")
+        if RECIPIENT_GROUP_TYPE_PATTERN.fullmatch(identifier) is None:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if (
+            radio.get("type") != "radio"
+            or radio.get("id") != "radio_" + identifier
+            or identifier in seen
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        labels = row.xpath(".//label")
+        if len(labels) != 1 or labels[0].get("for") != radio.get("id"):
+            raise LibrusError(ErrorKind.PARSE)
+        label = text(labels[0], RECIPIENT_MAX_LABEL_LENGTH)
+        if not label:
+            raise LibrusError(ErrorKind.PARSE)
+        if len(result) >= RECIPIENT_MAX_GROUPS:
+            raise LibrusError(ErrorKind.LIMIT)
+        seen.add(identifier)
+        result.append(
+            RecipientGroup(
+                RecipientGroupReference(identifier, account),
+                label,
+                radio.get("disabled") is None,
+                identifier not in RECIPIENT_UNSUPPORTED_TYPES,
+            )
+        )
+    if not result:
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(result)
+
+
+def parse_recipients(
+    body: bytes, group: RecipientGroupReference
+) -> tuple[Recipient, ...]:
+    validate_group(group, group.account)
+    document = _recipient_document(body)
+    if document.xpath('//p[@class="msgEmptyTable"]'):
+        # Explicit class-unavailable is handled above; unknown empty/prompt
+        # states must not silently coexist with a successful recipient list.
+        raise LibrusError(ErrorKind.PARSE)
+    result: list[Recipient] = []
+    seen: set[str] = set()
+    total = 0
+    labels = list(document.iter("label"))
+    controls_by_id = {n.get("id"): n for n in document.iter("input") if n.get("id")}
+    if not labels:
+        if group.identifier == "sadmin":
+            return _anonymous_recipient(document, group)
+        raise LibrusError(ErrorKind.PARSE)
+    for label in labels:
+        target = label.get("for", "")
+        match = re.fullmatch(r"(?:[A-Za-z][A-Za-z0-9]*_)+([0-9]{1,64})", target)
+        if match is None:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        identifier = match[1]
+        control = controls_by_id.get(target)
+        if (
+            control is None
+            or control.get("type") != "checkbox"
+            or control.get("value") != identifier
+            or identifier in seen
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        name = text(label, RECIPIENT_MAX_LABEL_LENGTH)
+        if not name:
+            raise LibrusError(ErrorKind.PARSE)
+        total += len(name)
+        if (
+            len(result) >= RECIPIENT_MAX_ITEMS
+            or total > RECIPIENT_MAX_TOTAL_TEXT_LENGTH
+        ):
+            raise LibrusError(ErrorKind.LIMIT)
+        seen.add(identifier)
+        result.append(
+            Recipient(
+                RecipientReference(
+                    identifier, group.account, group.identifier, group.selection_id
+                ),
+                name,
+            )
+        )
+    # The observed response has one ID/value-free select-all checkbox. Every
+    # recipient checkbox must instead have a numeric value and a matching label.
+    controls = 0
+    for node in document.iter("input"):
+        if node.get("type") != "checkbox":
+            continue
+        identifier, value = node.get("id"), node.get("value")
+        if identifier is None and value is None:
+            continue
+        if not identifier or re.fullmatch(r"[0-9]{1,64}", value or "") is None:
+            raise LibrusError(ErrorKind.PARSE)
+        controls += 1
+    if controls != len(result):
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(result)
+
+
+def _anonymous_recipient(
+    document: html.HtmlElement, group: RecipientGroupReference
+) -> tuple[Recipient, ...]:
+    controls = list(document.iter("input"))
+    if (
+        len(controls) != 2
+        or [c.get("name") for c in controls] != ["DoKogo", "DoKogo_hid[]"]
+        or any(
+            c.get("type", "").casefold() != "hidden" or c.get("id") for c in controls
+        )
+        or any(
+            isinstance(n.tag, str)
+            and n.tag not in {"html", "head", "body", "input", "script"}
+            for n in document.iter()
+        )
+        # Page-level scripts are inert and not display labels. They are never
+        # executed; only the exact hidden control pair defines this target.
+        or "".join(document.xpath("//text()[not(ancestor::script)]")).strip()
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    identifier = controls[0].get("value", "")
+    if (
+        re.fullmatch(r"[0-9]{1,64}", identifier) is None
+        or controls[1].get("value") != identifier
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    return (
+        Recipient(
+            RecipientReference(
+                identifier, group.account, group.identifier, group.selection_id
+            ),
+            None,
+        ),
+    )

librus_python_api/scheduler.py

@@ -0,0 +1,287 @@
+"""Bounded, round-robin admission across isolated configured accounts."""
+
+import asyncio
+import math
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, Self
+
+from librus_python_api.budget import RequestBudget
+from librus_python_api.config import SchedulerLimits
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.lifecycle import join_owned
+from librus_python_api.models import SchedulerSnapshot
+
+
+@dataclass(slots=True)
+class _Waiter:
+    ready: asyncio.Future[None]
+    granted: bool = False
+
+
+@dataclass(slots=True)
+class _Account:
+    queue: deque[_Waiter] = field(default_factory=deque)
+    active: int = 0
+
+
+class RequestScheduler:
+    """One event-loop-local scheduler reused by all account clients in a service.
+
+    Only admitted work gets an owned worker task. Excess work fails immediately;
+    no hidden semaphore waiters or unbounded worker queue is created. Calls are
+    scheduled FIFO within accounts and round-robin between eligible accounts.
+    `aclose` cancels and joins active workers before returning. This does not
+    enforce a distributed quota across independent services/processes.
+    """
+
+    def __init__(
+        self, accounts: tuple[str, ...], *, limits: SchedulerLimits | None = None
+    ) -> None:
+        self._limits = limits or SchedulerLimits()
+        if not accounts or len(accounts) > self._limits.accounts:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if any(
+            not isinstance(key, str) or not key or len(key) > 80 for key in accounts
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if len(set(accounts)) != len(accounts):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._accounts = {key: _Account() for key in accounts}
+        self._ring: deque[str] = deque()
+        self._active = self._queued = self._requests_dispatched = 0
+        self._tokens = float(self._limits.burst)
+        self._updated_at = time.monotonic()
+        self._pause_until = 0.0
+        self._resuming_without_burst = False
+        self._timer: asyncio.TimerHandle | None = None
+        self._workers: set[asyncio.Future[Any]] = set()
+        self._close_task: asyncio.Task[None] | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._closed = False
+
+    def snapshot(self) -> SchedulerSnapshot:
+        return SchedulerSnapshot(self._active, self._queued, self._requests_dispatched)
+
+    def _bind_loop(self) -> asyncio.AbstractEventLoop:
+        loop = asyncio.get_running_loop()
+        if self._loop is not None and self._loop is not loop:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._loop = loop
+        if self._closed:
+            raise LibrusError(ErrorKind.CLOSED)
+        return loop
+
+    async def run[T](
+        self,
+        account: str,
+        budget: RequestBudget,
+        action: Callable[[], Awaitable[T]],
+        *,
+        preserve_completed: bool = False,
+    ) -> T:
+        loop = self._bind_loop()
+        state = self._accounts.get(account)
+        if state is None:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        budget._bind_loop()
+        budget.check()
+        waiter = _Waiter(loop.create_future())
+        self._enqueue(account, state, waiter)
+        try:
+            async with asyncio.timeout(budget.remaining_seconds()):
+                await waiter.ready
+                if self._closed:
+                    raise LibrusError(ErrorKind.CLOSED)
+                budget._consume()
+                self._requests_dispatched += 1
+                worker = asyncio.ensure_future(action())
+                self._workers.add(worker)
+                try:
+                    await asyncio.wait((worker,))
+                    result = worker.result()
+                    if not preserve_completed:
+                        budget.remaining_seconds()
+                    return result
+                except asyncio.CancelledError:
+                    if not isinstance(worker, asyncio.Task) or not worker.cancelling():
+                        worker.cancel()
+                    await join_owned(worker)
+                    if self._closed:
+                        raise LibrusError(ErrorKind.CLOSED) from None
+                    raise
+                finally:
+                    self._workers.discard(worker)
+        except TimeoutError:
+            raise LibrusError(ErrorKind.TIMEOUT) from None
+        finally:
+            self._release(account, state, waiter)
+
+    def _enqueue(self, account: str, state: _Account, waiter: _Waiter) -> None:
+        self._refill()
+        immediate = (
+            not self._ring
+            and self._active < self._limits.active_requests
+            and state.active < self._limits.active_requests_per_account
+            and self._tokens >= 1
+            and time.monotonic() >= self._pause_until
+        )
+        if immediate:
+            self._grant(state, waiter)
+            return
+        if (
+            self._queued >= self._limits.queued_requests
+            or len(state.queue) >= self._limits.queued_requests_per_account
+        ):
+            raise LibrusError(ErrorKind.LIMIT)
+        if not state.queue:
+            self._ring.append(account)
+        state.queue.append(waiter)
+        self._queued += 1
+        self._drain()
+
+    def _grant(self, state: _Account, waiter: _Waiter) -> None:
+        assert self._active < self._limits.active_requests
+        assert state.active < self._limits.active_requests_per_account
+        assert self._tokens >= 1
+        self._tokens -= 1
+        state.active += 1
+        self._active += 1
+        waiter.granted = True
+        waiter.ready.set_result(None)
+
+    def _release(self, account: str, state: _Account, waiter: _Waiter) -> None:
+        if waiter.granted:
+            state.active -= 1
+            self._active -= 1
+            assert state.active >= 0
+            assert self._active >= 0
+        elif waiter in state.queue:
+            state.queue.remove(waiter)
+            self._queued -= 1
+            if not state.queue:
+                self._ring.remove(account)
+        if not waiter.ready.done():
+            waiter.ready.cancel()
+        self._drain()
+        if (
+            waiter.granted
+            and self._active == 0
+            and not self._ring
+            and time.monotonic() >= self._pause_until
+        ):
+            self._resuming_without_burst = False
+
+    def _refill(self) -> None:
+        now = time.monotonic()
+        elapsed = max(0.0, now - self._updated_at)
+        capacity = 1 if self._resuming_without_burst else self._limits.burst
+        self._tokens = min(
+            float(capacity),
+            self._tokens + elapsed * self._limits.requests_per_second,
+        )
+        self._updated_at = max(now, self._pause_until)
+
+    def _drain(self) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+        if self._closed:
+            return
+        self._refill()
+        while self._ring and self._active < self._limits.active_requests:
+            state = self._next_eligible()
+            if state is None:
+                return
+            delay = max(
+                self._pause_until - time.monotonic(),
+                (1 - self._tokens) / self._limits.requests_per_second,
+            )
+            if delay > 0:
+                assert self._loop is not None
+                self._timer = self._loop.call_later(delay, self._drain)
+                return
+            waiter = state.queue.popleft()
+            self._queued -= 1
+            account = self._ring.popleft()
+            if state.queue:
+                self._ring.append(account)
+            self._grant(state, waiter)
+
+    def _next_eligible(self) -> _Account | None:
+        for _ in range(len(self._ring)):
+            if not self._ring:
+                return None
+            state = self._accounts[self._ring[0]]
+            while state.queue and state.queue[0].ready.done():
+                state.queue.popleft()
+                self._queued -= 1
+            if not state.queue:
+                self._ring.popleft()
+                continue
+            if state.active < self._limits.active_requests_per_account:
+                return state
+            self._ring.rotate(-1)
+        return None
+
+    def pause_for(self, seconds: float) -> None:
+        """Pause shared dispatch and resume gradually, without a full burst."""
+        self._bind_loop()
+        if (
+            type(seconds) not in (int, float)
+            or not math.isfinite(seconds)
+            or seconds < 0
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._pause_until = max(self._pause_until, time.monotonic() + seconds)
+        # Keep resume credit capped until admitted work and its backlog drain.
+        # A delayed event-loop timer must not rebuild a burst during a pause.
+        self._resuming_without_burst = True
+        self._tokens = 0.0
+        self._updated_at = self._pause_until
+        self._drain()
+
+    async def aclose(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is not None and self._loop is not loop:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._loop = loop
+        if asyncio.current_task() in self._workers:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if self._close_task is None:
+            self._closed = True
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            for state in self._accounts.values():
+                for waiter in state.queue:
+                    if not waiter.ready.done():
+                        waiter.ready.set_exception(LibrusError(ErrorKind.CLOSED))
+            self._close_task = asyncio.create_task(self._finish_close())
+        try:
+            await asyncio.shield(self._close_task)
+        except asyncio.CancelledError:
+            await join_owned(self._close_task)
+            raise
+
+    async def _finish_close(self) -> None:
+        workers = tuple(self._workers)
+        for worker in workers:
+            if not isinstance(worker, asyncio.Task) or not worker.cancelling():
+                worker.cancel()
+        await asyncio.gather(*workers, return_exceptions=True)
+
+    async def __aenter__(self) -> Self:
+        self._bind_loop()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()