borgee-plugin-sdk 0.1.2__py3-none-any.whl

borgee_plugin_sdk/cursor.py

@@ -0,0 +1,220 @@
+"""Durable monotonic cursor stores."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import fcntl
+import json
+import os
+import stat
+import threading
+import time
+import uuid
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Protocol, TypeVar, runtime_checkable
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class CursorStore(Protocol):
+    async def read(self, key: str) -> int: ...
+    async def write(self, key: str, cursor: int) -> None: ...
+
+
+class MemoryCursorStore:
+    """Process-local cursor storage with monotonic writes."""
+
+    def __init__(self) -> None:
+        self._values: dict[str, int] = {}
+        self._lock = asyncio.Lock()
+
+    async def read(self, key: str) -> int:
+        async with self._lock:
+            return self._values.get(key, 0)
+
+    async def write(self, key: str, cursor: int) -> None:
+        _validate_cursor(key, cursor)
+        async with self._lock:
+            self._values[key] = max(cursor, self._values.get(key, 0))
+
+
+class _OperationCancelled(Exception):
+    pass
+
+
+class FileCursorStore:
+    """POSIX cursor file protected by a separate advisory lock file."""
+
+    def __init__(self, path: str | os.PathLike[str], *, lock_timeout: float = 5.0) -> None:
+        if lock_timeout <= 0:
+            raise ValueError("lock_timeout must be positive")
+        self.path = Path(path)
+        self.lock_timeout = lock_timeout
+        self._lock_path = self.path.with_name(self.path.name + ".lock")
+
+    async def read(self, key: str) -> int:
+        if not key:
+            raise ValueError("cursor key must not be empty")
+        cancel = threading.Event()
+        return await self._run_worker(self._read_sync, key, cancel)
+
+    async def write(self, key: str, cursor: int) -> None:
+        _validate_cursor(key, cursor)
+        cancel = threading.Event()
+        await self._run_worker(self._write_sync, key, cursor, cancel)
+
+    async def _run_worker(self, function: Callable[..., T], *args: object) -> T:
+        cancel = args[-1]
+        assert isinstance(cancel, threading.Event)
+        worker: asyncio.Task[T] = asyncio.create_task(asyncio.to_thread(function, *args))
+        try:
+            return await asyncio.shield(worker)
+        except asyncio.CancelledError:
+            cancel.set()
+            with contextlib.suppress(_OperationCancelled):
+                await asyncio.shield(worker)
+            raise
+
+    def _read_sync(self, key: str, cancel: threading.Event) -> int:
+        self._ensure_secure_parent()
+        lock_fd = self._acquire_lock(fcntl.LOCK_SH, cancel)
+        try:
+            self._validate_existing_file(self.path)
+            values = self._read_values()
+            return values.get(key, 0)
+        finally:
+            self._release_lock(lock_fd)
+
+    def _write_sync(self, key: str, cursor: int, cancel: threading.Event) -> None:
+        self._ensure_secure_parent()
+        lock_fd = self._acquire_lock(fcntl.LOCK_EX, cancel)
+        temp_path: Path | None = None
+        try:
+            self._validate_existing_file(self.path)
+            values = self._read_values()
+            if cursor <= values.get(key, 0):
+                return
+            values[key] = cursor
+            encoded = (json.dumps(values, sort_keys=True, separators=(",", ":")) + "\n").encode()
+            temp_path = self.path.with_name(f".{self.path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+            flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+            if hasattr(os, "O_NOFOLLOW"):
+                flags |= os.O_NOFOLLOW
+            fd = os.open(temp_path, flags, 0o600)
+            try:
+                os.fchmod(fd, 0o600)
+                view = memoryview(encoded)
+                while view:
+                    written = os.write(fd, view)
+                    view = view[written:]
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+            if cancel.is_set():
+                raise _OperationCancelled
+
+            # Once rename starts, the worker must finish directory fsync. The
+            # async wrapper shields and awaits this old-or-new durable commit.
+            os.replace(temp_path, self.path)
+            temp_path = None
+            directory_fd = os.open(self.path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        finally:
+            if temp_path is not None:
+                with contextlib.suppress(OSError):
+                    temp_path.unlink()
+            self._release_lock(lock_fd)
+
+    def _ensure_secure_parent(self) -> None:
+        parent = self.path.parent
+        try:
+            info = parent.lstat()
+        except FileNotFoundError:
+            try:
+                parent.mkdir(mode=0o700, parents=True, exist_ok=False)
+            except FileExistsError:
+                # Another process may have created the same parent after our
+                # lstat. Re-read it below and apply the full ownership, mode,
+                # symlink, and directory checks before using it.
+                pass
+            info = parent.lstat()
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+            raise OSError(f"cursor directory is not a real directory: {parent}")
+        if info.st_uid != os.geteuid():
+            raise PermissionError(f"cursor directory is not owned by the current user: {parent}")
+        if stat.S_IMODE(info.st_mode) & 0o077:
+            raise PermissionError(f"cursor directory permissions must be 0700: {parent}")
+
+    def _validate_existing_file(self, path: Path) -> None:
+        try:
+            info = path.lstat()
+        except FileNotFoundError:
+            return
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+            raise OSError(f"cursor path is not a regular file: {path}")
+        if info.st_uid != os.geteuid():
+            raise PermissionError(f"cursor file is not owned by the current user: {path}")
+        if stat.S_IMODE(info.st_mode) & 0o077:
+            raise PermissionError(f"cursor file permissions must not grant group or other access: {path}")
+
+    def _acquire_lock(self, operation: int, cancel: threading.Event) -> int:
+        self._validate_existing_file(self._lock_path)
+        flags = os.O_RDWR | os.O_CREAT
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        fd = os.open(self._lock_path, flags, 0o600)
+        try:
+            os.fchmod(fd, 0o600)
+            deadline = time.monotonic() + self.lock_timeout
+            while True:
+                if cancel.is_set():
+                    raise _OperationCancelled
+                try:
+                    fcntl.flock(fd, operation | fcntl.LOCK_NB)
+                    return fd
+                except BlockingIOError:
+                    if time.monotonic() >= deadline:
+                        raise TimeoutError(f"cursor lock timed out after {self.lock_timeout:.3f}s") from None
+                    cancel.wait(min(0.01, max(0.0, deadline - time.monotonic())))
+        except BaseException:
+            os.close(fd)
+            raise
+
+    @staticmethod
+    def _release_lock(fd: int) -> None:
+        with contextlib.suppress(OSError):
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+    def _read_values(self) -> dict[str, int]:
+        try:
+            raw = self.path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        value = json.loads(raw)
+        if not isinstance(value, Mapping):
+            raise ValueError("cursor file must contain a JSON object")
+        result: dict[str, int] = {}
+        for key, cursor in value.items():
+            if (
+                not isinstance(key, str)
+                or not isinstance(cursor, int)
+                or isinstance(cursor, bool)
+                or cursor < 0
+            ):
+                raise ValueError("cursor file contains an invalid entry")
+            result[key] = cursor
+        return result
+
+
+def _validate_cursor(key: str, cursor: int) -> None:
+    if not key:
+        raise ValueError("cursor key must not be empty")
+    if not isinstance(cursor, int) or isinstance(cursor, bool) or cursor < 0:
+        raise ValueError("cursor must be a non-negative integer")

borgee_plugin_sdk/errors.py

@@ -0,0 +1,61 @@
+"""Public SDK exceptions."""
+
+from __future__ import annotations
+
+
+class BorgeeError(Exception):
+    """Base SDK error with a stable machine-readable code."""
+
+    def __init__(self, message: str, code: str = "borgee.error") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class PermissionDeniedError(BorgeeError):
+    def __init__(
+        self,
+        message: str = "permission denied",
+        *,
+        attempted_action: str = "",
+        required_capability: str = "",
+        current_scope: str = "",
+    ) -> None:
+        super().__init__(message, "bpp.permission_denied")
+        self.attempted_action = attempted_action
+        self.required_capability = required_capability
+        self.current_scope = current_scope
+
+
+class NotOnlineError(BorgeeError):
+    def __init__(self, message: str = "plugin is not online") -> None:
+        super().__init__(message, "bpp.not_online")
+
+
+class ProtocolError(BorgeeError):
+    def __init__(self, message: str, code: str = "bpp.protocol_error") -> None:
+        super().__init__(message, code)
+
+
+class ProtocolCapacityError(ProtocolError):
+    def __init__(self, message: str = "protocol capacity exceeded") -> None:
+        super().__init__(message, "bpp.protocol_capacity")
+
+
+class StaleDeliveryError(BorgeeError):
+    def __init__(self, message: str = "delivery belongs to a stale connection") -> None:
+        super().__init__(message, "bpp.stale_delivery")
+
+
+class ResumeAckError(ProtocolError):
+    def __init__(self, message: str, code: str = "bpp.resume_ack_invalid") -> None:
+        super().__init__(message, code)
+
+
+class PreResumeError(ProtocolError):
+    def __init__(self, message: str, code: str = "bpp.pre_resume_failed") -> None:
+        super().__init__(message, code)
+
+
+class CursorStoreError(BorgeeError):
+    def __init__(self, message: str, code: str = "bpp.cursor_store_failed") -> None:
+        super().__init__(message, code)

borgee_plugin_sdk/models.py

@@ -0,0 +1,326 @@
+"""Public domain models for the Python plugin SDK."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol, TypeAlias, runtime_checkable
+
+
+class _Missing:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING = _Missing()
+MissingType: TypeAlias = _Missing
+
+
+class ReplayMode(StrEnum):
+    FULL = "full"
+    SUMMARY = "summary"
+    LATEST_N = "latest_n"
+
+
+class ConnectionStatus(StrEnum):
+    CONNECTING = "connecting"
+    RESUMING = "resuming"
+    ONLINE = "online"
+    RECONNECTING = "reconnecting"
+    ERROR = "error"
+    CLOSED = "closed"
+
+
+class UserRole(StrEnum):
+    MEMBER = "member"
+    AGENT = "agent"
+
+
+class InboundKind(StrEnum):
+    MESSAGE = "message"
+    EDITED = "edited"
+    DELETED = "deleted"
+    REACTION = "reaction"
+    MENTION = "mention"
+
+
+class TaskOutcome(StrEnum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class FaultReason(StrEnum):
+    API_KEY_INVALID = "api_key_invalid"
+    QUOTA_EXCEEDED = "quota_exceeded"
+    NETWORK_UNREACHABLE = "network_unreachable"
+    RUNTIME_CRASHED = "runtime_crashed"
+    RUNTIME_TIMEOUT = "runtime_timeout"
+    UNKNOWN = "unknown"
+
+
+class ConfigApplyStatus(StrEnum):
+    APPLIED = "applied"
+    REJECTED = "rejected"
+    STALE = "stale"
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionState:
+    status: ConnectionStatus
+    attempt: int = 0
+    reason: FaultReason | None = None
+    code: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    id: str
+    display_name: str
+    role: str
+    permissions: tuple[str, ...]
+    avatar_url: str | None = None
+    email: str | None = None
+    created_at: int | None = None
+    last_seen_at: int | None = None
+    require_mention: bool | None = None
+    owner_id: str | None = None
+    deleted_at: int | None = None
+    disabled: bool | None = None
+
+    @property
+    def kind(self) -> str:
+        return "agent" if self.role == UserRole.AGENT.value else "user"
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    id: str
+    channel_id: str
+    author_id: str
+    body: str
+    created_at: int
+    content_type: str | None = None
+    reply_to_id: str | None = None
+    edited_at: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SentMessage:
+    message_id: str
+    cursor: int
+
+
+@dataclass(frozen=True, slots=True)
+class CreatedDM:
+    channel_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseFrame:
+    """Presence-sensitive plugin response envelope."""
+
+    id: str
+    data: Any | MissingType = field(default=MISSING)
+    error: str | MissingType = field(default=MISSING)
+
+    @property
+    def has_data(self) -> bool:
+        return self.data is not MISSING
+
+    @property
+    def has_error(self) -> bool:
+        return self.error is not MISSING
+
+    @classmethod
+    def from_wire(cls, value: Any) -> ResponseFrame:
+        if not isinstance(value, dict) or not isinstance(value.get("id"), str):
+            raise TypeError("response frame must contain a string id")
+        has_data = "data" in value
+        has_error = "error" in value
+        if has_data == has_error:
+            raise ValueError("response frame must contain exactly one of data or error")
+        if has_error and (not isinstance(value["error"], str) or not value["error"]):
+            raise TypeError("response error must be a non-empty string")
+        return cls(
+            id=value["id"],
+            data=value["data"] if has_data else MISSING,
+            error=value["error"] if has_error else MISSING,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class InboundReaction:
+    emoji: str
+    user_id: str
+    added: bool
+
+
+@dataclass(frozen=True, slots=True)
+class InboundMessageEvent:
+    kind: InboundKind
+    cursor: int
+    channel_id: str
+    created_at: int
+    channel_type: str | None = None
+    message: Message | None = None
+    message_id: str | None = None
+    reaction: InboundReaction | None = None
+    author_name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ReplaySummaryEvent:
+    cursor: int
+    missed_count: int
+    since_cursor: int
+    through_cursor: int
+    summary: str
+
+
+DeliveryEvent: TypeAlias = InboundMessageEvent | ReplaySummaryEvent
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigUpdate:
+    agent_id: str
+    schema_version: int
+    blob: Any
+    idempotency_key: str
+    cursor: int
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigApplyResult:
+    status: ConfigApplyStatus
+    reason: FaultReason | None = None
+
+
+@dataclass(slots=True)
+class ConfigApplyContext:
+    cancelled: asyncio.Event
+
+
+@dataclass(frozen=True, slots=True)
+class ServerRequest:
+    action: str
+    params: Any
+
+
+@runtime_checkable
+class Logger(Protocol):
+    def debug(self, message: str, *args: Any) -> None: ...
+    def info(self, message: str, *args: Any) -> None: ...
+    def warning(self, message: str, *args: Any) -> None: ...
+    def error(self, message: str, *args: Any) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    id: str
+    channel_id: str
+    guild_id: str
+    seq: int
+    title: str
+    description: str
+    status: str
+    assignee_id: str | None
+    created_by: str
+    message_id: str | None
+    thread_id: str | None
+    created_at: int
+    updated_at: int
+    heartbeat_prompt: str
+
+
+def task_from_wire(value: Any) -> Task:
+    """Deserialize a task wire dict into a Task dataclass."""
+    if not isinstance(value, dict):
+        raise TypeError("task result must be an object")
+    task_id = value.get("id")
+    if not isinstance(task_id, str) or not task_id:
+        raise TypeError("task id must be a non-empty string")
+    return Task(
+        id=task_id,
+        channel_id=value.get("channel_id", ""),
+        guild_id=value.get("guild_id", ""),
+        seq=value.get("seq", 0),
+        title=value.get("title", ""),
+        description=value.get("description", ""),
+        status=value.get("status", ""),
+        assignee_id=value.get("assignee_id"),
+        created_by=value.get("created_by", ""),
+        message_id=value.get("message_id"),
+        thread_id=value.get("thread_id"),
+        created_at=value.get("created_at", 0),
+        updated_at=value.get("updated_at", 0),
+        heartbeat_prompt=value.get("heartbeat_prompt", ""),
+    )
+
+
+def user_from_wire(value: Any) -> User:
+    if not isinstance(value, dict):
+        raise TypeError("get_me result must be an object")
+    required = ("id", "display_name", "role", "permissions")
+    if any(key not in value for key in required):
+        raise TypeError("get_me result is missing a required user field")
+    user_id = _required_non_empty_string(value["id"], "id")
+    display_name = _required_non_empty_string(value["display_name"], "display_name")
+    role = _required_non_empty_string(value["role"], "role")
+    if role not in {item.value for item in UserRole}:
+        raise TypeError("user role must be member or agent")
+    permissions = value["permissions"]
+    if not isinstance(permissions, list):
+        raise TypeError("user permissions must be a string list")
+    if not all(isinstance(item, str) and bool(item.strip()) for item in permissions):
+        raise TypeError("user permissions must contain only non-empty strings")
+    return User(
+        id=user_id,
+        display_name=display_name,
+        role=role,
+        permissions=tuple(permissions),
+        avatar_url=_optional_string_field(value, "avatar_url"),
+        email=_optional_string_field(value, "email"),
+        created_at=_optional_integer_field(value, "created_at"),
+        last_seen_at=_optional_integer_field(value, "last_seen_at"),
+        require_mention=_optional_boolean_field(value, "require_mention"),
+        owner_id=_optional_string_field(value, "owner_id"),
+        deleted_at=_optional_integer_field(value, "deleted_at"),
+        disabled=_optional_boolean_field(value, "disabled"),
+    )
+
+
+def _required_non_empty_string(value: Any, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(f"user {field_name} must be a non-empty string")
+    return value
+
+
+def _optional_string_field(value: dict[Any, Any], field_name: str) -> str | None:
+    field = value.get(field_name)
+    if field is None:
+        return None
+    if not isinstance(field, str):
+        raise TypeError(f"user {field_name} must be a string or null")
+    return field
+
+
+def _optional_integer_field(value: dict[Any, Any], field_name: str) -> int | None:
+    field = value.get(field_name)
+    if field is None:
+        return None
+    if not isinstance(field, int) or isinstance(field, bool) or field < 0:
+        raise TypeError(f"user {field_name} must be a non-negative integer or null")
+    return field
+
+
+def _optional_boolean_field(value: dict[Any, Any], field_name: str) -> bool | None:
+    field = value.get(field_name)
+    if field is None:
+        return None
+    if not isinstance(field, bool):
+        raise TypeError(f"user {field_name} must be a boolean or null")
+    return field

borgee_plugin_sdk/py.typed

@@ -0,0 +1 @@
+

borgee_plugin_sdk/testing/__init__.py

@@ -0,0 +1,16 @@
+"""Testing helpers. Internal transports are intentionally absent from the root API."""
+
+from __future__ import annotations
+
+from ..client import BorgeePluginClient, BorgeePluginOptions
+from .fake_transport import FakeDelivery, FakeTransport, RecordedAction
+
+
+def create_test_client(
+    options: BorgeePluginOptions,
+    transport: FakeTransport,
+) -> BorgeePluginClient:
+    return BorgeePluginClient(options, transport)  # type: ignore[arg-type]
+
+
+__all__ = ["FakeDelivery", "FakeTransport", "RecordedAction", "create_test_client"]