roomkit 0.1.0__py3-none-any.whl

roomkit/core/_channel_ops.py

@@ -0,0 +1,252 @@
+"""ChannelOpsMixin — channel registration, binding, and state management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from roomkit.core._helpers import HelpersMixin
+from roomkit.models.channel import ChannelBinding
+from roomkit.models.enums import (
+    Access,
+    ChannelCategory,
+    ChannelType,
+    EventType,
+    HookTrigger,
+)
+
+if TYPE_CHECKING:
+    from roomkit.channels.base import Channel
+    from roomkit.core.event_router import EventRouter
+    from roomkit.core.locks import RoomLockManager
+    from roomkit.store.base import ConversationStore
+
+
+class ChannelOpsMixin(HelpersMixin):
+    """Channel registration, attachment, and binding operations."""
+
+    _store: ConversationStore
+    _channels: dict[str, Channel]
+    _lock_manager: RoomLockManager
+    _event_router: EventRouter | None
+
+    def register_channel(self, channel: Channel) -> None:
+        """Register a channel implementation by its ID."""
+        self._channels[channel.channel_id] = channel
+        self._event_router = None  # Reset router cache
+
+    async def attach_channel(
+        self,
+        room_id: str,
+        channel_id: str,
+        channel_type: ChannelType | None = None,
+        category: ChannelCategory = ChannelCategory.TRANSPORT,
+        access: Access = Access.READ_WRITE,
+        visibility: str = "all",
+        **kwargs: Any,
+    ) -> ChannelBinding:
+        """Attach a registered channel to a room."""
+        from roomkit.core.framework import ChannelNotRegisteredError
+
+        async with self._lock_manager.locked(room_id):
+            await self.get_room(room_id)  # type: ignore[attr-defined]
+            channel = self._channels.get(channel_id)
+            if channel is None:
+                raise ChannelNotRegisteredError(f"Channel {channel_id} not registered")
+            ct = channel_type or channel.channel_type
+            binding = ChannelBinding(
+                channel_id=channel_id,
+                room_id=room_id,
+                channel_type=ct,
+                category=category,
+                access=access,
+                visibility=visibility,
+                capabilities=channel.capabilities(),
+                **kwargs,
+            )
+            result = await self._store.add_binding(binding)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_ATTACHED,
+                code="channel_attached",
+                message=f"Channel {channel_id} attached ({access}, {visibility})",
+                data={
+                    "channel_id": channel_id,
+                    "access": str(access),
+                    "visibility": visibility,
+                },
+            )
+            await self._fire_lifecycle_hook(
+                room_id,
+                HookTrigger.ON_CHANNEL_ATTACHED,
+                EventType.CHANNEL_ATTACHED,
+                code="channel_attached",
+                message=f"Channel {channel_id} attached",
+                data={
+                    "channel_id": channel_id,
+                    "access": str(access),
+                    "visibility": visibility,
+                },
+            )
+            await self._emit_framework_event(
+                "room_channel_attached",
+                room_id=room_id,
+                channel_id=channel_id,
+                data={"access": str(access), "visibility": visibility},
+            )
+            return result
+
+    async def detach_channel(self, room_id: str, channel_id: str) -> bool:
+        """Detach a channel from a room."""
+        async with self._lock_manager.locked(room_id):
+            removed = await self._store.remove_binding(room_id, channel_id)
+            if removed:
+                await self._emit_system_event(
+                    room_id,
+                    EventType.CHANNEL_DETACHED,
+                    code="channel_detached",
+                    message=f"Channel {channel_id} detached",
+                    data={"channel_id": channel_id},
+                )
+                await self._fire_lifecycle_hook(
+                    room_id,
+                    HookTrigger.ON_CHANNEL_DETACHED,
+                    EventType.CHANNEL_DETACHED,
+                    code="channel_detached",
+                    message=f"Channel {channel_id} detached",
+                    data={"channel_id": channel_id},
+                )
+                await self._emit_framework_event(
+                    "room_channel_detached",
+                    room_id=room_id,
+                    channel_id=channel_id,
+                )
+            return removed
+
+    async def mute(self, room_id: str, channel_id: str) -> ChannelBinding:
+        """Mute a channel in a room."""
+        async with self._lock_manager.locked(room_id):
+            binding = await self._get_binding(room_id, channel_id)
+            updated = binding.model_copy(update={"muted": True})
+            result = await self._store.update_binding(updated)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_MUTED,
+                code="channel_muted",
+                message=f"Channel {channel_id} muted",
+                data={"channel_id": channel_id},
+            )
+            await self._fire_lifecycle_hook(
+                room_id,
+                HookTrigger.ON_CHANNEL_MUTED,
+                EventType.CHANNEL_MUTED,
+                code="channel_muted",
+                message=f"Channel {channel_id} muted",
+                data={"channel_id": channel_id},
+            )
+            return result
+
+    async def unmute(self, room_id: str, channel_id: str) -> ChannelBinding:
+        """Unmute a channel in a room."""
+        async with self._lock_manager.locked(room_id):
+            binding = await self._get_binding(room_id, channel_id)
+            updated = binding.model_copy(update={"muted": False})
+            result = await self._store.update_binding(updated)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_UNMUTED,
+                code="channel_unmuted",
+                message=f"Channel {channel_id} unmuted",
+                data={"channel_id": channel_id},
+            )
+            await self._fire_lifecycle_hook(
+                room_id,
+                HookTrigger.ON_CHANNEL_UNMUTED,
+                EventType.CHANNEL_UNMUTED,
+                code="channel_unmuted",
+                message=f"Channel {channel_id} unmuted",
+                data={"channel_id": channel_id},
+            )
+            return result
+
+    async def set_visibility(
+        self, room_id: str, channel_id: str, visibility: str
+    ) -> ChannelBinding:
+        """Set visibility for a channel in a room."""
+        async with self._lock_manager.locked(room_id):
+            binding = await self._get_binding(room_id, channel_id)
+            old_visibility = binding.visibility
+            updated = binding.model_copy(update={"visibility": visibility})
+            result = await self._store.update_binding(updated)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_UPDATED,
+                code="channel_visibility_changed",
+                message=f"Channel {channel_id} visibility: {old_visibility} -> {visibility}",
+                data={
+                    "channel_id": channel_id,
+                    "old_visibility": old_visibility,
+                    "visibility": visibility,
+                },
+            )
+            return result
+
+    async def set_access(self, room_id: str, channel_id: str, access: Access) -> ChannelBinding:
+        """Set access level for a channel in a room."""
+        async with self._lock_manager.locked(room_id):
+            binding = await self._get_binding(room_id, channel_id)
+            old_access = binding.access
+            updated = binding.model_copy(update={"access": access})
+            result = await self._store.update_binding(updated)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_UPDATED,
+                code="channel_access_changed",
+                message=f"Channel {channel_id} access: {old_access} -> {access}",
+                data={
+                    "channel_id": channel_id,
+                    "old_access": str(old_access),
+                    "access": str(access),
+                },
+            )
+            return result
+
+    async def update_binding_metadata(
+        self, room_id: str, channel_id: str, metadata: dict[str, Any]
+    ) -> ChannelBinding:
+        """Update metadata on a channel binding."""
+        async with self._lock_manager.locked(room_id):
+            binding = await self._get_binding(room_id, channel_id)
+            updated = binding.model_copy(update={"metadata": {**binding.metadata, **metadata}})
+            result = await self._store.update_binding(updated)
+            await self._emit_system_event(
+                room_id,
+                EventType.CHANNEL_UPDATED,
+                code="channel_metadata_updated",
+                message=f"Channel {channel_id} metadata updated",
+                data={"channel_id": channel_id, "keys": list(metadata.keys())},
+            )
+            return result
+
+    def get_channel(self, channel_id: str) -> Channel | None:
+        """Get a registered channel by ID."""
+        return self._channels.get(channel_id)
+
+    def list_channels(self) -> list[Channel]:
+        """List all registered channels."""
+        return list(self._channels.values())
+
+    async def get_binding(self, room_id: str, channel_id: str) -> ChannelBinding:
+        """Get a channel binding. Raises ChannelNotFoundError if missing."""
+        return await self._get_binding(room_id, channel_id)
+
+    async def list_bindings(self, room_id: str) -> list[ChannelBinding]:
+        """List all channel bindings for a room."""
+        return await self._store.list_bindings(room_id)
+
+    async def _get_binding(self, room_id: str, channel_id: str) -> ChannelBinding:
+        from roomkit.core.framework import ChannelNotFoundError
+
+        binding = await self._store.get_binding(room_id, channel_id)
+        if binding is None:
+            raise ChannelNotFoundError(f"Channel {channel_id} not in room {room_id}")
+        return binding

roomkit/core/_helpers.py

@@ -0,0 +1,296 @@
+"""HelpersMixin — internal helpers shared across framework mixins."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Coroutine
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+from roomkit.models.context import RoomContext
+from roomkit.models.enums import (
+    ChannelType,
+    EventStatus,
+    EventType,
+    HookTrigger,
+    IdentificationStatus,
+)
+from roomkit.models.event import EventSource, RoomEvent, SystemContent
+from roomkit.models.framework_event import FrameworkEvent
+from roomkit.models.identity import Identity, IdentityHookResult, IdentityResult
+from roomkit.models.participant import Participant
+from roomkit.models.task import Observation, Task
+
+if TYPE_CHECKING:
+    from roomkit.core.hooks import HookEngine, IdentityHookRegistration
+    from roomkit.store.base import ConversationStore
+
+logger = logging.getLogger("roomkit.framework")
+
+FrameworkEventHandler = Callable[[FrameworkEvent], Coroutine[Any, Any, None]]
+IdentityHookFn = Callable[
+    [RoomEvent, RoomContext, IdentityResult],
+    Coroutine[Any, Any, IdentityHookResult | None],
+]
+
+
+class HelpersMixin:
+    """Internal helpers used by other framework mixins."""
+
+    _store: ConversationStore
+    _hook_engine: HookEngine
+    _event_handlers: list[tuple[str, FrameworkEventHandler]]
+    _identity_hooks: dict[HookTrigger, list[IdentityHookRegistration]]
+
+    # -- Internal helpers --
+
+    def _identity_hook_matches_event(
+        self, hook: IdentityHookRegistration, event: RoomEvent
+    ) -> bool:
+        """Check if an identity hook's filters match the given event."""
+        source = event.source
+
+        # All filters must pass (None means "match all")
+        type_ok = hook.channel_types is None or source.channel_type in hook.channel_types
+        id_ok = hook.channel_ids is None or source.channel_id in hook.channel_ids
+        dir_ok = hook.directions is None or source.direction in hook.directions
+
+        return type_ok and id_ok and dir_ok
+
+    async def _run_identity_hooks(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        event: RoomEvent,
+        context: RoomContext,
+        id_result: IdentityResult,
+    ) -> IdentityHookResult | None:
+        """Run identity hooks for *trigger*, return the first non-None result."""
+        hooks = self._identity_hooks.get(trigger, [])
+        for hook_reg in hooks:
+            # Apply filters
+            if not self._identity_hook_matches_event(hook_reg, event):
+                continue
+            try:
+                result: IdentityHookResult | None = await hook_reg.fn(event, context, id_result)
+                if result is not None:
+                    return result
+            except Exception:
+                logger.exception(
+                    "Identity hook failed for trigger %s",
+                    trigger,
+                    extra={"room_id": room_id, "trigger": str(trigger)},
+                )
+        return None
+
+    async def _create_pending_participant(
+        self,
+        room_id: str,
+        event: RoomEvent,
+        id_result: IdentityResult,
+    ) -> Participant:
+        """Create a participant with pending identification status.
+
+        Idempotent: if a participant with the same ID already exists in the room,
+        the existing record is returned without creating a duplicate.
+        """
+        participant_id = event.source.participant_id or f"pending-{uuid4().hex[:8]}"
+        existing = await self._store.get_participant(room_id, participant_id)
+        if existing is not None:
+            return existing
+        candidate_ids = [c.id for c in id_result.candidates] if id_result.candidates else None
+        participant = Participant(
+            id=participant_id,
+            room_id=room_id,
+            channel_id=event.source.channel_id,
+            identification=IdentificationStatus.PENDING,
+            candidates=candidate_ids,
+        )
+        participant = await self._store.add_participant(participant)
+        await self._emit_system_event(
+            room_id,
+            EventType.PARTICIPANT_JOINED,
+            code="participant_joined_pending",
+            message=f"Participant {participant.id} joined with pending identification",
+            data={"participant_id": participant.id, "status": "pending"},
+        )
+        return participant
+
+    async def _ensure_identified_participant(
+        self,
+        room_id: str,
+        event: RoomEvent,
+        identity: Identity,
+    ) -> Participant:
+        """Ensure a participant record exists for an identified identity.
+
+        Idempotent: if a participant with the identity's ID already exists in the room,
+        the existing record is returned without creating a duplicate.
+        """
+        existing = await self._store.get_participant(room_id, identity.id)
+        if existing is not None:
+            # Update identification status if it was pending
+            if existing.identification != IdentificationStatus.IDENTIFIED:
+                existing = existing.model_copy(
+                    update={
+                        "identification": IdentificationStatus.IDENTIFIED,
+                        "identity_id": identity.id,
+                        "display_name": identity.display_name or existing.display_name,
+                    }
+                )
+                existing = await self._store.update_participant(existing)
+            return existing
+
+        participant = Participant(
+            id=identity.id,
+            room_id=room_id,
+            channel_id=event.source.channel_id,
+            display_name=identity.display_name,
+            identification=IdentificationStatus.IDENTIFIED,
+            identity_id=identity.id,
+        )
+        participant = await self._store.add_participant(participant)
+        await self._emit_system_event(
+            room_id,
+            EventType.PARTICIPANT_JOINED,
+            code="participant_joined_identified",
+            message=f"Participant {participant.id} joined as identified",
+            data={"participant_id": participant.id, "status": "identified"},
+        )
+        return participant
+
+    async def _fire_lifecycle_hook(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        event_type: EventType,
+        code: str,
+        message: str,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Fire an async lifecycle hook with a synthetic system event."""
+        event = RoomEvent(
+            room_id=room_id,
+            type=event_type,
+            source=EventSource(channel_id="system", channel_type=ChannelType.SYSTEM),
+            content=SystemContent(body=message, code=code, data=data or {}),
+            status=EventStatus.DELIVERED,
+            visibility="internal",
+        )
+        try:
+            context = await self._build_context(room_id)
+        except Exception:
+            # Room may not exist yet (e.g. ON_ROOM_CREATED before bindings exist)
+            room = await self._store.get_room(room_id)
+            if room is None:
+                return
+            context = RoomContext(room=room, bindings=[])
+        await self._hook_engine.run_async_hooks(room_id, trigger, event, context)
+
+    async def _persist_side_effects(
+        self,
+        room_id: str,
+        tasks: list[Task],
+        observations: list[Observation],
+        event: RoomEvent,
+        context: RoomContext,
+    ) -> None:
+        """Persist tasks and observations, fire ON_TASK_CREATED hooks for new tasks."""
+        persisted_tasks: list[Task] = []
+        for task in tasks:
+            try:
+                await self._store.add_task(task)
+                persisted_tasks.append(task)
+            except Exception:
+                logger.exception(
+                    "Failed to persist task %s",
+                    task.id,
+                    extra={"room_id": room_id, "task_id": task.id},
+                )
+        for observation in observations:
+            try:
+                await self._store.add_observation(observation)
+            except Exception:
+                logger.exception(
+                    "Failed to persist observation %s",
+                    observation.id,
+                    extra={"room_id": room_id, "observation_id": observation.id},
+                )
+        # Fire ON_TASK_CREATED hooks only for successfully persisted tasks
+        for task in persisted_tasks:
+            task_event = RoomEvent(
+                room_id=room_id,
+                type=EventType.TASK_CREATED,
+                source=event.source,
+                content=event.content,
+                status=EventStatus.DELIVERED,
+                visibility="internal",
+                metadata={"task_id": task.id, "task_title": task.title},
+            )
+            await self._hook_engine.run_async_hooks(
+                room_id, HookTrigger.ON_TASK_CREATED, task_event, context
+            )
+
+    async def _emit_system_event(
+        self,
+        room_id: str,
+        event_type: EventType,
+        code: str,
+        message: str,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Emit a system event to the room timeline (internal/audit)."""
+        count = await self._store.get_event_count(room_id)
+        event = RoomEvent(
+            room_id=room_id,
+            type=event_type,
+            source=EventSource(channel_id="system", channel_type=ChannelType.SYSTEM),
+            content=SystemContent(body=message, code=code, data=data or {}),
+            status=EventStatus.DELIVERED,
+            visibility="internal",
+            index=count,
+        )
+        await self._store.add_event(event)
+
+    async def _build_context(self, room_id: str) -> RoomContext:
+        """Build a RoomContext for the given room."""
+        room = await self._store.get_room(room_id)
+        if room is None:
+            from roomkit.core.framework import RoomNotFoundError
+
+            raise RoomNotFoundError(f"Room {room_id} not found")
+        bindings = await self._store.list_bindings(room_id)
+        participants = await self._store.list_participants(room_id)
+        recent = await self._store.list_events(room_id, offset=0, limit=50)
+        return RoomContext(
+            room=room,
+            bindings=bindings,
+            participants=participants,
+            recent_events=recent,
+        )
+
+    async def _emit_framework_event(
+        self,
+        event_type: str,
+        room_id: str | None = None,
+        channel_id: str | None = None,
+        event_id: str | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Emit a framework event to handlers registered for *event_type*."""
+        fw_event = FrameworkEvent(
+            type=event_type,
+            room_id=room_id,
+            channel_id=channel_id,
+            event_id=event_id,
+            data=data or {},
+        )
+        for filter_type, handler in self._event_handlers:
+            if filter_type == fw_event.type:
+                try:
+                    await handler(fw_event)
+                except Exception:
+                    logger.exception(
+                        "Framework event handler failed",
+                        extra={"event_type": fw_event.type, "room_id": fw_event.room_id},
+                    )