netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/management/__init__.py

@@ -0,0 +1,83 @@
+"""Application management boundary shared by Feishu and Admin adapters."""
+
+from .coordination import ScopeCoordinator
+from .chat_labels import ChatLabel, ChatLabelProvider, ChatLabelResolver
+from .service import (
+    ActivePointerChanged,
+    BindingPrimaryStatusResolution,
+    BindingStatusProjection,
+    BindingScopeMismatch,
+    ClosedSide,
+    CreatedBinding,
+    CurrentBindingChanged,
+    CurrentBindingTarget,
+    CurrentSideTarget,
+    ExactBindingTarget,
+    InstanceManagementService,
+    ManagementError,
+    ManagementRuntimePort,
+    NativeCatalogInconsistent,
+    NativeThreadMissing,
+    NativeThreadView,
+    NoCurrentBinding,
+    ProjectInventoryItem,
+    ProjectInventoryPage,
+    ProjectDeletionResult,
+    ReleasedBinding,
+    RenamedBinding,
+    RuntimePrecondition,
+    RuntimeSnapshots,
+    RuntimeStateChanged,
+    SessionInventoryItem,
+    SessionInventoryPage,
+    SessionInventoryState,
+    SessionQuery,
+    ScopeSessionPage,
+    SideIdentityMismatch,
+    SideTopicInventoryItem,
+    SideTopicInventoryPage,
+    StoppedBinding,
+    classify_native_thread_view,
+)
+
+__all__ = (
+    "ActivePointerChanged",
+    "BindingPrimaryStatusResolution",
+    "BindingStatusProjection",
+    "BindingScopeMismatch",
+    "ChatLabel",
+    "ChatLabelProvider",
+    "ChatLabelResolver",
+    "ClosedSide",
+    "CreatedBinding",
+    "CurrentBindingChanged",
+    "CurrentBindingTarget",
+    "CurrentSideTarget",
+    "ExactBindingTarget",
+    "InstanceManagementService",
+    "ManagementError",
+    "ManagementRuntimePort",
+    "NativeCatalogInconsistent",
+    "NativeThreadMissing",
+    "NativeThreadView",
+    "NoCurrentBinding",
+    "ProjectInventoryItem",
+    "ProjectInventoryPage",
+    "ProjectDeletionResult",
+    "ReleasedBinding",
+    "RenamedBinding",
+    "RuntimePrecondition",
+    "RuntimeSnapshots",
+    "RuntimeStateChanged",
+    "ScopeCoordinator",
+    "SessionInventoryItem",
+    "SessionInventoryPage",
+    "SessionInventoryState",
+    "SessionQuery",
+    "ScopeSessionPage",
+    "SideIdentityMismatch",
+    "SideTopicInventoryItem",
+    "SideTopicInventoryPage",
+    "StoppedBinding",
+    "classify_native_thread_view",
+)

netizen_cli/management/blocking_io.py

@@ -0,0 +1,352 @@
+"""Bounded execution for blocking management-plane filesystem work.
+
+The executor deliberately counts submitted ``concurrent.futures.Future``
+objects rather than asyncio Tasks.  Cancelling an HTTP handler therefore only
+stops that handler from waiting; it neither cancels the blocking operation nor
+returns its admission slot early.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import threading
+from concurrent.futures import Future, ThreadPoolExecutor
+from functools import partial
+from typing import Callable, TypeVar
+
+
+ResultT = TypeVar("ResultT")
+
+
+class BlockingIOExecutorClosed(RuntimeError):
+    """Raised when work is submitted after admission has closed."""
+
+
+class BlockingIOExecutorSaturated(RuntimeError):
+    """Raised when all running and queued work slots are occupied."""
+
+
+class BlockingIOResultUnknown(RuntimeError):
+    """A submitted operation did not finish before its response deadline.
+
+    The underlying operation is not cancelled and remains tracked by the
+    executor.  Callers must reconcile the authoritative state; they must not
+    infer rollback or retry the operation automatically.
+    """
+
+    def __init__(self, *, deadline: float) -> None:
+        self.deadline = deadline
+        super().__init__(
+            "blocking I/O deadline expired after submission; result is unknown "
+            "and the operation remains tracked"
+        )
+
+
+class BlockingIODrainTimeout(TimeoutError):
+    """Raised when tracked work cannot drain within the caller's budget."""
+
+    def __init__(self, *, in_flight: int, deadline: float) -> None:
+        self.in_flight = in_flight
+        self.deadline = deadline
+        super().__init__(
+            f"blocking I/O drain deadline expired with {in_flight} operation(s) "
+            "still tracked"
+        )
+
+
+class BlockingIOShutdownTimeout(TimeoutError):
+    """Raised when the worker-thread join exceeds the caller's budget."""
+
+    def __init__(self, *, deadline: float) -> None:
+        self.deadline = deadline
+        super().__init__("blocking I/O worker shutdown exceeded its deadline")
+
+
+class BoundedBlockingIOExecutor:
+    """Run synchronous callables without an unbounded executor queue.
+
+    ``capacity`` counts both running and queued operations.  Admission is
+    rejected synchronously within :meth:`submit` before
+    :class:`ThreadPoolExecutor` sees the callable.  The instance belongs to one
+    asyncio event loop, while its completion accounting is protected for
+    callbacks arriving from worker threads.
+
+    ``deadline`` values are absolute values from the owning loop's monotonic
+    clock (``loop.time()``), which is suitable for sharing one shutdown or
+    request budget across several awaits.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_workers: int = 1,
+        capacity: int = 2,
+        thread_name_prefix: str = "netizen-project-io",
+    ) -> None:
+        if (
+            isinstance(max_workers, bool)
+            or not isinstance(max_workers, int)
+            or max_workers < 1
+        ):
+            raise ValueError("max_workers must be a positive integer")
+        if (
+            isinstance(capacity, bool)
+            or not isinstance(capacity, int)
+            or capacity < max_workers
+        ):
+            raise ValueError("capacity must be an integer at least max_workers")
+        if not thread_name_prefix:
+            raise ValueError("thread_name_prefix must not be empty")
+
+        self._capacity = capacity
+        self._executor = ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix=thread_name_prefix,
+        )
+        self._state_lock = threading.Lock()
+        self._tracked: set[Future[object]] = set()
+        self._accepting = True
+        self._shutdown_started = False
+
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._completion_event: asyncio.Event | None = None
+        self._join_task: asyncio.Task[None] | None = None
+        self._join_error: BaseException | None = None
+        self._joined = False
+
+    @property
+    def capacity(self) -> int:
+        return self._capacity
+
+    @property
+    def accepting(self) -> bool:
+        with self._state_lock:
+            return self._accepting
+
+    @property
+    def in_flight(self) -> int:
+        """Return the number of running or queued underlying operations."""
+
+        with self._state_lock:
+            return len(self._tracked)
+
+    @property
+    def joined(self) -> bool:
+        return self._joined
+
+    async def submit(
+        self,
+        function: Callable[..., ResultT],
+        /,
+        *args: object,
+        deadline: float | None = None,
+        **kwargs: object,
+    ) -> ResultT:
+        """Submit a synchronous callable and asynchronously await its result.
+
+        A deadline applies only to waiting for the already-submitted operation.
+        Expiry raises :class:`BlockingIOResultUnknown`; it never cancels or
+        retries the underlying future.
+        """
+
+        loop, _ = self._bind_to_running_loop()
+        checked_deadline = _validate_deadline(deadline)
+        operation = partial(function, *args, **kwargs)
+
+        with self._state_lock:
+            if not self._accepting:
+                raise BlockingIOExecutorClosed(
+                    "blocking I/O executor is closed to new work"
+                )
+            if len(self._tracked) >= self._capacity:
+                raise BlockingIOExecutorSaturated(
+                    "blocking I/O executor has no free submission slots"
+                )
+            # This is the only call into ThreadPoolExecutor.submit.  Keeping it
+            # in the same critical section as the checks guarantees that a
+            # rejected operation never reaches its unbounded internal queue.
+            future = self._executor.submit(operation)
+            self._tracked.add(future)
+
+        future.add_done_callback(self._operation_completed)
+        wrapped = asyncio.wrap_future(future, loop=loop)
+        # If the request is cancelled or times out, nobody may await ``wrapped``
+        # again.  Retrieve a later exception to prevent an asyncio warning;
+        # this does not change the result seen by a normal waiter.
+        wrapped.add_done_callback(_consume_asyncio_future_exception)
+
+        if checked_deadline is None:
+            return await asyncio.shield(wrapped)
+
+        remaining = checked_deadline - loop.time()
+        if remaining > 0:
+            done, _ = await asyncio.wait((wrapped,), timeout=remaining)
+            if done:
+                return wrapped.result()
+
+        # Cover completion racing the timeout without claiming uncertainty
+        # when the concurrent result is already synchronously available.
+        if future.done():
+            return future.result()
+        raise BlockingIOResultUnknown(deadline=checked_deadline)
+
+    def close_admission(self) -> None:
+        """Idempotently reject all future submissions without cancelling work."""
+
+        with self._state_lock:
+            self._accepting = False
+
+    async def drain(self, *, deadline: float | None = None) -> None:
+        """Wait for all tracked operations within an optional absolute deadline."""
+
+        loop, completion_event = self._bind_to_running_loop()
+        checked_deadline = _validate_deadline(deadline)
+
+        while True:
+            # Clear before checking while the worker callback cannot acquire
+            # the state lock.  A completion after the check schedules a fresh
+            # set(), so no wakeup can be lost.
+            completion_event.clear()
+            with self._state_lock:
+                remaining_work = len(self._tracked)
+            if remaining_work == 0:
+                return
+
+            if checked_deadline is None:
+                await completion_event.wait()
+                continue
+
+            remaining_time = checked_deadline - loop.time()
+            if remaining_time <= 0:
+                raise BlockingIODrainTimeout(
+                    in_flight=remaining_work,
+                    deadline=checked_deadline,
+                )
+            try:
+                await asyncio.wait_for(
+                    completion_event.wait(),
+                    timeout=remaining_time,
+                )
+            except TimeoutError:
+                with self._state_lock:
+                    remaining_work = len(self._tracked)
+                if remaining_work == 0:
+                    return
+                raise BlockingIODrainTimeout(
+                    in_flight=remaining_work,
+                    deadline=checked_deadline,
+                ) from None
+
+    async def aclose(self, *, deadline: float | None = None) -> None:
+        """Close admission, drain tracked work, and join worker threads.
+
+        The operation is idempotent.  Cancellation or deadline expiry leaves
+        admission closed and the submitted work running to completion; a later
+        call can finish draining and joining it.
+        """
+
+        loop, _ = self._bind_to_running_loop()
+        checked_deadline = _validate_deadline(deadline)
+        self.close_admission()
+        self._start_executor_shutdown()
+
+        await self.drain(deadline=checked_deadline)
+        if self._joined:
+            if self._join_error is not None:
+                raise self._join_error
+            return
+
+        join_task = self._join_task
+        if join_task is None:
+            join_task = asyncio.create_task(
+                asyncio.to_thread(
+                    self._executor.shutdown,
+                    wait=True,
+                    cancel_futures=False,
+                ),
+                name="netizen-blocking-io-shutdown",
+            )
+            join_task.add_done_callback(self._executor_joined)
+            self._join_task = join_task
+
+        if checked_deadline is None:
+            await asyncio.shield(join_task)
+        else:
+            remaining = checked_deadline - loop.time()
+            if remaining <= 0:
+                if not join_task.done():
+                    raise BlockingIOShutdownTimeout(deadline=checked_deadline)
+            else:
+                done, _ = await asyncio.wait((join_task,), timeout=remaining)
+                if not done:
+                    raise BlockingIOShutdownTimeout(deadline=checked_deadline)
+
+        # The callback consumes and records exceptions for deadline/cancelled
+        # callers; result() here preserves normal close failure propagation.
+        join_task.result()
+
+    def _bind_to_running_loop(
+        self,
+    ) -> tuple[asyncio.AbstractEventLoop, asyncio.Event]:
+        loop = asyncio.get_running_loop()
+        with self._state_lock:
+            if self._loop is None:
+                self._loop = loop
+                self._completion_event = asyncio.Event()
+            elif self._loop is not loop:
+                raise RuntimeError(
+                    "BoundedBlockingIOExecutor cannot be used across event loops"
+                )
+            completion_event = self._completion_event
+        assert completion_event is not None
+        return loop, completion_event
+
+    def _operation_completed(self, future: Future[object]) -> None:
+        with self._state_lock:
+            self._tracked.discard(future)
+            loop = self._loop
+            completion_event = self._completion_event
+        if loop is None or completion_event is None:
+            return
+        try:
+            loop.call_soon_threadsafe(completion_event.set)
+        except RuntimeError:
+            # The service is expected to drain before closing its event loop.
+            # Accounting is already correct even if a broken shutdown cannot
+            # be woken after the loop itself has disappeared.
+            pass
+
+    def _start_executor_shutdown(self) -> None:
+        with self._state_lock:
+            if self._shutdown_started:
+                return
+            self._shutdown_started = True
+        # wait=False never cancels queued work and returns immediately.  A
+        # later off-loop wait=True call performs the clean thread join.
+        self._executor.shutdown(wait=False, cancel_futures=False)
+
+    def _executor_joined(self, task: asyncio.Task[None]) -> None:
+        try:
+            task.result()
+        except BaseException as error:
+            self._join_error = error
+        else:
+            self._joined = True
+
+
+def _validate_deadline(deadline: float | None) -> float | None:
+    if deadline is None:
+        return None
+    if isinstance(deadline, bool) or not isinstance(deadline, (int, float)):
+        raise TypeError("deadline must be a finite monotonic timestamp")
+    checked = float(deadline)
+    if not math.isfinite(checked):
+        raise ValueError("deadline must be a finite monotonic timestamp")
+    return checked
+
+
+def _consume_asyncio_future_exception(future: asyncio.Future[object]) -> None:
+    if future.cancelled():
+        return
+    future.exception()

netizen_cli/management/chat_labels.py

@@ -0,0 +1,266 @@
+"""Best-effort Feishu chat labels for management inventory pages."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import OrderedDict
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+_POSITIVE_TTL_SECONDS = 10 * 60.0
+_NEGATIVE_TTL_SECONDS = 30.0
+_CACHE_CAPACITY = 4_096
+_LOOKUP_CONCURRENCY = 10
+_LOOKUP_BUDGET_SECONDS = 2.5
+
+
+class ChatLabelProvider(Protocol):
+    async def get_chat_info(self, chat_id: str) -> Any: ...
+
+    async def get_chat_members(
+        self,
+        chat_id: str,
+        *,
+        page_size: int = 100,
+        max_pages: int = 10,
+        id_type: str = "open_id",
+        force: bool = False,
+    ) -> Sequence[Any]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ChatLabel:
+    chat_id: str
+    display_name: str
+    chat_mode: str | None
+    resolved: bool = True
+    p2p_target_open_id: str | None = None
+    chat_type: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _CacheEntry:
+    label: ChatLabel
+    expires_at: float
+
+
+class ChatLabelResolver:
+    """Resolve only requested chat IDs with bounded TTL/LRU caching."""
+
+    def __init__(
+        self,
+        provider: ChatLabelProvider,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        positive_ttl_seconds: float = _POSITIVE_TTL_SECONDS,
+        negative_ttl_seconds: float = _NEGATIVE_TTL_SECONDS,
+        capacity: int = _CACHE_CAPACITY,
+        concurrency: int = _LOOKUP_CONCURRENCY,
+        lookup_budget_seconds: float = _LOOKUP_BUDGET_SECONDS,
+    ) -> None:
+        if positive_ttl_seconds <= 0 or negative_ttl_seconds <= 0:
+            raise ValueError("chat label TTLs must be positive")
+        if capacity < 1:
+            raise ValueError("chat label cache capacity must be positive")
+        if concurrency < 1:
+            raise ValueError("chat label lookup concurrency must be positive")
+        if lookup_budget_seconds <= 0:
+            raise ValueError("chat label lookup budget must be positive")
+        self._provider = provider
+        self._clock = clock
+        self._positive_ttl_seconds = positive_ttl_seconds
+        self._negative_ttl_seconds = negative_ttl_seconds
+        self._capacity = capacity
+        self._semaphore = asyncio.Semaphore(concurrency)
+        self._lookup_budget_seconds = lookup_budget_seconds
+        self._cache: OrderedDict[str, _CacheEntry] = OrderedDict()
+        self._inflight: dict[str, asyncio.Task[ChatLabel]] = {}
+
+    async def resolve_many(
+        self,
+        chat_ids: Iterable[str],
+        *,
+        deadline: float,
+    ) -> dict[str, ChatLabel]:
+        unique = tuple(dict.fromkeys(chat_ids))
+        labels: dict[str, ChatLabel] = {}
+        tasks: dict[str, asyncio.Task[ChatLabel]] = {}
+        loop = asyncio.get_running_loop()
+        lookup_deadline = min(deadline, loop.time() + self._lookup_budget_seconds)
+
+        for chat_id in unique:
+            cached = self._get_cached(chat_id)
+            if cached is not None:
+                labels[chat_id] = cached
+                continue
+            task = self._inflight.get(chat_id)
+            if task is None:
+                task = asyncio.create_task(
+                    self._resolve_one(chat_id, deadline=lookup_deadline)
+                )
+                self._inflight[chat_id] = task
+                task.add_done_callback(
+                    lambda completed, resolved_id=chat_id: self._finish(
+                        resolved_id,
+                        completed,
+                    )
+                )
+            tasks[chat_id] = task
+
+        if tasks:
+            timeout = max(0.0, lookup_deadline - loop.time())
+            await asyncio.wait(set(tasks.values()), timeout=timeout)
+            for chat_id, task in tasks.items():
+                if not task.done() or task.cancelled():
+                    labels[chat_id] = self.fallback(chat_id)
+                    continue
+                try:
+                    labels[chat_id] = task.result()
+                except Exception:
+                    labels[chat_id] = self.fallback(chat_id)
+
+        return labels
+
+    async def aclose(self) -> None:
+        tasks = tuple(self._inflight.values())
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        self._inflight.clear()
+        self._cache.clear()
+
+    @staticmethod
+    def fallback(
+        chat_id: str,
+        *,
+        chat_mode: str | None = None,
+        chat_type: str | None = None,
+        p2p_target_open_id: str | None = None,
+    ) -> ChatLabel:
+        return ChatLabel(
+            chat_id=chat_id,
+            display_name=chat_id,
+            chat_mode=chat_mode,
+            resolved=False,
+            p2p_target_open_id=p2p_target_open_id,
+            chat_type=chat_type,
+        )
+
+    def _get_cached(self, chat_id: str) -> ChatLabel | None:
+        entry = self._cache.get(chat_id)
+        if entry is None:
+            return None
+        if entry.expires_at <= self._clock():
+            del self._cache[chat_id]
+            return None
+        self._cache.move_to_end(chat_id)
+        return entry.label
+
+    def _finish(self, chat_id: str, task: asyncio.Task[ChatLabel]) -> None:
+        if self._inflight.get(chat_id) is task:
+            del self._inflight[chat_id]
+        if task.cancelled():
+            return
+        try:
+            label = task.result()
+        except Exception:
+            label = self.fallback(chat_id)
+        ttl = (
+            self._positive_ttl_seconds
+            if label.resolved
+            else self._negative_ttl_seconds
+        )
+        self._cache[chat_id] = _CacheEntry(label, self._clock() + ttl)
+        self._cache.move_to_end(chat_id)
+        while len(self._cache) > self._capacity:
+            self._cache.popitem(last=False)
+
+    async def _resolve_one(self, chat_id: str, *, deadline: float) -> ChatLabel:
+        try:
+            async with self._semaphore:
+                info = await self._before_deadline(
+                    self._provider.get_chat_info(chat_id),
+                    deadline=deadline,
+                )
+                if info is None:
+                    return self.fallback(chat_id)
+                name = self._text(getattr(info, "name", None))
+                chat_mode = self._text(getattr(info, "chat_mode", None))
+                chat_type = self._text(getattr(info, "chat_type", None))
+                p2p_target_open_id = None
+                if chat_mode == "p2p":
+                    try:
+                        members = await self._before_deadline(
+                            self._provider.get_chat_members(
+                                chat_id,
+                                page_size=100,
+                                max_pages=1,
+                                id_type="open_id",
+                            ),
+                            deadline=deadline,
+                        )
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception:
+                        if not name:
+                            return self.fallback(
+                                chat_id,
+                                chat_mode=chat_mode,
+                                chat_type=chat_type,
+                            )
+                        members = ()
+                    member_name, p2p_target_open_id = self._p2p_member(members)
+                    name = member_name or name
+                if not name:
+                    return self.fallback(
+                        chat_id,
+                        chat_mode=chat_mode,
+                        chat_type=chat_type,
+                        p2p_target_open_id=p2p_target_open_id,
+                    )
+                return ChatLabel(
+                    chat_id=chat_id,
+                    display_name=name,
+                    chat_mode=chat_mode,
+                    resolved=True,
+                    p2p_target_open_id=p2p_target_open_id,
+                    chat_type=chat_type,
+                )
+        except asyncio.CancelledError:
+            raise
+        except TimeoutError:
+            return self.fallback(chat_id)
+        except Exception:
+            return self.fallback(chat_id)
+
+    @staticmethod
+    async def _before_deadline(awaitable: Any, *, deadline: float) -> Any:
+        remaining = deadline - asyncio.get_running_loop().time()
+        if remaining <= 0:
+            if hasattr(awaitable, "close"):
+                awaitable.close()
+            raise TimeoutError("chat label lookup deadline elapsed")
+        return await asyncio.wait_for(awaitable, timeout=remaining)
+
+    @classmethod
+    def _p2p_member(cls, members: Sequence[Any]) -> tuple[str, str | None]:
+        candidates: list[tuple[str, str | None]] = []
+        for member in members:
+            name = cls._text(getattr(member, "name", None))
+            member_id = cls._text(getattr(member, "id", None))
+            id_type = cls._text(getattr(member, "id_type", None))
+            if name:
+                candidates.append(
+                    (name, member_id if id_type == "open_id" else None)
+                )
+        if len(candidates) != 1:
+            return "", None
+        return candidates[0]
+
+    @staticmethod
+    def _text(value: Any) -> str:
+        return value.strip() if isinstance(value, str) else ""