jararaca 0.2.37a12__py3-none-any.whl → 0.4.0a5__py3-none-any.whl

jararaca/presentation/websocket/websocket_interceptor.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import asyncio
 import inspect
 from contextlib import asynccontextmanager
@@ -13,9 +17,9 @@ from pydantic import BaseModel
 from jararaca.core.uow import UnitOfWorkContextProvider
 from jararaca.di import Container
 from jararaca.microservice import (
-    AppContext,
     AppInterceptor,
     AppInterceptorWithLifecycle,
+    AppTransactionContext,
     Microservice,
 )
 from jararaca.presentation.decorators import (
@@ -25,7 +29,9 @@ from jararaca.presentation.decorators import (
 )
 from jararaca.presentation.websocket.context import (
     WebSocketConnectionManager,
+    WebSocketMessageSender,
     provide_ws_manager,
+    provide_ws_message_sender,
 )
 from jararaca.presentation.websocket.decorators import (
     INHERITS_WS_MESSAGE,
@@ -83,13 +89,24 @@ class WebSocketConnectionManagerImpl(WebSocketConnectionManager):
         await self.backend.broadcast(message)
 
     async def _broadcast_from_backend(self, message: bytes) -> None:
-        for websocket in self.all_websockets:
+        # Create a copy of the websockets set to avoid modification during iteration
+        async with self.lock:
+            websockets_to_send = list(self.all_websockets)
+
+        disconnected_websockets: list[WebSocket] = []
+
+        for websocket in websockets_to_send:
             try:
                 if websocket.client_state == WebSocketState.CONNECTED:
                     await websocket.send_bytes(message)
             except WebSocketDisconnect:
-                async with self.lock:  # TODO: check if this can cause concurrency slowdown issues
-                    self.all_websockets.remove(websocket)
+                disconnected_websockets.append(websocket)
+
+        # Clean up disconnected websockets in a single lock acquisition
+        if disconnected_websockets:
+            async with self.lock:
+                for websocket in disconnected_websockets:
+                    self.all_websockets.discard(websocket)
 
     async def send(self, rooms: list[str], message: WebSocketMessageBase) -> None:
 
@@ -101,16 +118,28 @@ class WebSocketConnectionManagerImpl(WebSocketConnectionManager):
         )
 
     async def _send_from_backend(self, rooms: list[str], message: bytes) -> None:
+        # Create a copy of room memberships to avoid modification during iteration
         async with self.lock:
-            for room in rooms:
-                for websocket in self.rooms.get(room, set()):
-                    try:
-                        if websocket.client_state == WebSocketState.CONNECTED:
-                            await websocket.send_bytes(message)
-                    except WebSocketDisconnect:
-                        async with self.lock:
-                            if websocket in self.rooms[room]:
-                                self.rooms[room].remove(websocket)
+            room_websockets: dict[str, list[WebSocket]] = {
+                room: list(self.rooms.get(room, set())) for room in rooms
+            }
+
+        disconnected_by_room: dict[str, list[WebSocket]] = {room: [] for room in rooms}
+
+        for room, websockets in room_websockets.items():
+            for websocket in websockets:
+                try:
+                    if websocket.client_state == WebSocketState.CONNECTED:
+                        await websocket.send_bytes(message)
+                except WebSocketDisconnect:
+                    disconnected_by_room[room].append(websocket)
+
+        # Clean up disconnected websockets in a single lock acquisition
+        async with self.lock:
+            for room, disconnected_websockets in disconnected_by_room.items():
+                if room in self.rooms:
+                    for websocket in disconnected_websockets:
+                        self.rooms[room].discard(websocket)
 
     async def join(self, rooms: list[str], websocket: WebSocket) -> None:
         for room in rooms:
@@ -127,9 +156,23 @@ class WebSocketConnectionManagerImpl(WebSocketConnectionManager):
     # async def setup_consumer(self, websocket: WebSocket) -> None: ...
 
 
+class StagingWebSocketMessageSender(WebSocketMessageSender):
+
+    def __init__(self, connection: WebSocketConnectionManager) -> None:
+        self.connection = connection
+        self.staged_messages: list[tuple[list[str], WebSocketMessageBase]] = []
+
+    async def send(self, rooms: list[str], message: WebSocketMessageBase) -> None:
+        self.staged_messages.append((rooms, message))
+
+    async def flush(self) -> None:
+        for rooms, message in self.staged_messages:
+            await self.connection.send(rooms, message)
+        self.staged_messages.clear()
+
+
 class WebSocketInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
     """
-    @Deprecated
     WebSocketInterceptor is responsible for managing WebSocket connections and
     intercepting WebSocket requests within the application. It integrates with
     the application's lifecycle and provides a router for WebSocket endpoints.
@@ -169,10 +212,18 @@ class WebSocketInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
         self.shutdown_event.set()
 
     @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def intercept(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
 
-        with provide_ws_manager(self.connection_manager):
+        staging_ws_messages_sender = StagingWebSocketMessageSender(
+            self.connection_manager
+        )
+        with provide_ws_manager(self.connection_manager), provide_ws_message_sender(
+            staging_ws_messages_sender
+        ):
             yield
+            await staging_ws_messages_sender.flush()
 
     # def __wrap_with_uow_context_provider(
     #     self, uow: UnitOfWorkContextProvider, func: Callable[..., Any]
@@ -198,13 +249,15 @@ class WebSocketInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
 
         for controller_type in app.controllers:
 
-            rest_controller = RestController.get_controller(controller_type)
+            rest_controller = RestController.get_last(controller_type)
             controller: Any = container.get_by_type(controller_type)
 
-            members = inspect.getmembers(controller_type, predicate=inspect.isfunction)
+            members = inspect.getmembers_static(
+                controller_type, predicate=inspect.isfunction
+            )
 
             for name, member in members:
-                if (ws_endpoint := WebSocketEndpoint.get(member)) is not None:
+                if (ws_endpoint := WebSocketEndpoint.get_last(member)) is not None:
                     final_path = (
                         rest_controller.path + ws_endpoint.path
                         if rest_controller
@@ -212,7 +265,7 @@ class WebSocketInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
                     )
 
                     route_dependencies: list[Depends] = []
-                    for middlewares_by_hook in UseMiddleware.get_middlewares(
+                    for middlewares_by_hook in UseMiddleware.get(
                         getattr(controller_type, name)
                     ):
                         middleware_instance = container.get_by_type(
@@ -222,9 +275,7 @@ class WebSocketInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
                             Depends(middleware_instance.intercept)
                         )
 
-                    for dependency in UseDependency.get_dependencies(
-                        getattr(controller_type, name)
-                    ):
+                    for dependency in UseDependency.get(getattr(controller_type, name)):
                         route_dependencies.append(DependsF(dependency.dependency))
 
                     api_router.add_api_websocket_route(

jararaca/reflect/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later

jararaca/reflect/controller_inspect.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Tuple, Type
+
+from frozendict import frozendict
+
+from jararaca.reflect.metadata import SetMetadata, TransactionMetadata
+
+
+@dataclass(frozen=True)
+class ControllerReflect:
+
+    controller_class: Type[Any]
+    metadata: Mapping[str, TransactionMetadata]
+
+
+@dataclass(frozen=True)
+class ControllerMemberReflect:
+    controller_reflect: ControllerReflect
+    member_function: Callable[..., Any]
+    metadata: Mapping[str, TransactionMetadata]
+
+
+def inspect_controller(
+    controller: Type[Any],
+) -> Tuple[ControllerReflect, Mapping[str, ControllerMemberReflect]]:
+    """
+    Inspect a controller class to extract its metadata and member functions.
+
+    Args:
+        controller (Type[Any]): The controller class to inspect.
+
+    Returns:
+        Tuple[ControllerReflect, list[ControllerMemberReflect]]: A tuple containing the controller reflect and a list of member reflects.
+    """
+    controller_metadata_list = SetMetadata.get(controller)
+
+    controller_metadata_map = frozendict(
+        {
+            metadata.key: TransactionMetadata(
+                value=metadata.value, inherited_from_controller=False
+            )
+            for metadata in controller_metadata_list
+        }
+    )
+
+    controller_reflect = ControllerReflect(
+        controller_class=controller, metadata=controller_metadata_map
+    )
+
+    members = {
+        name: ControllerMemberReflect(
+            controller_reflect=controller_reflect,
+            member_function=member,
+            metadata=frozendict(
+                {
+                    **{
+                        key: TransactionMetadata(
+                            value=value.value, inherited_from_controller=True
+                        )
+                        for key, value in controller_metadata_map.items()
+                    },
+                    **{
+                        metadata.key: TransactionMetadata(
+                            value=metadata.value, inherited_from_controller=False
+                        )
+                        for metadata in SetMetadata.get(member)
+                    },
+                }
+            ),
+        )
+        for name, member in inspect.getmembers_static(
+            controller, predicate=inspect.isfunction
+        )
+    }
+
+    return controller_reflect, members

jararaca/reflect/decorators.py

@@ -0,0 +1,238 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Callable, Self, TypedDict, TypeVar, cast
+
+DECORATED_T = TypeVar("DECORATED_T", bound="Callable[..., Any] | type")
+
+
+S = TypeVar("S", bound="StackableDecorator")
+
+
+class DecoratorMetadata(TypedDict):
+    decorators: "list[StackableDecorator]"
+    decorators_by_type: "dict[Any, list[StackableDecorator]]"
+
+
+class StackableDecorator:
+    _ATTR_NAME: str = "__jararaca_stackable_decorator__"
+
+    def __call__(self, subject: DECORATED_T) -> DECORATED_T:
+        self.pre_decorated(subject)
+        self.register(subject, self)
+        self.post_decorated(subject)
+        return subject
+
+    @classmethod
+    def decorator_key(cls) -> Any:
+        return cls
+
+    @classmethod
+    def get_or_set_metadata(cls, subject: Any) -> DecoratorMetadata:
+        if cls._ATTR_NAME not in subject.__dict__:
+            setattr(
+                subject,
+                cls._ATTR_NAME,
+                DecoratorMetadata(decorators=[], decorators_by_type={}),
+            )
+        return cast(DecoratorMetadata, getattr(subject, cls._ATTR_NAME))
+
+    @classmethod
+    def get_metadata(cls, subject: Any) -> DecoratorMetadata | None:
+        if hasattr(subject, cls._ATTR_NAME):
+            return cast(DecoratorMetadata, getattr(subject, cls._ATTR_NAME))
+        return None
+
+    @classmethod
+    def register(cls, subject: Any, decorator: "StackableDecorator") -> None:
+        if not cls._ATTR_NAME:
+            raise NotImplementedError("Subclasses must define _ATTR_NAME")
+
+        metadata = cls.get_or_set_metadata(subject)
+        metadata["decorators"].append(decorator)
+        metadata["decorators_by_type"].setdefault(cls.decorator_key(), []).append(
+            decorator
+        )
+
+    @classmethod
+    def get(cls, subject: Any) -> list[Self]:
+        metadata = cls.get_metadata(subject)
+        if metadata is None:
+            return []
+
+        if cls is StackableDecorator:
+            return cast(list[Self], metadata["decorators"])
+        else:
+            return cast(
+                list[Self], metadata["decorators_by_type"].get(cls.decorator_key(), [])
+            )
+
+    @classmethod
+    def extract_list(cls, subject: Any) -> list[Self]:
+        metadata = cls.get_metadata(subject)
+        if metadata is None:
+            return []
+
+        if cls is StackableDecorator:
+            return cast(list[Self], metadata["decorators"])
+        else:
+            return cast(
+                list[Self], metadata["decorators_by_type"].get(cls.decorator_key(), [])
+            )
+
+    @classmethod
+    def get_fisrt(cls, subject: Any) -> Self | None:
+        decorators = cls.get(subject)
+        if decorators:
+            return decorators[0]
+        return None
+
+    @classmethod
+    def get_last(cls, subject: Any) -> Self | None:
+        decorators = cls.get(subject)
+        if decorators:
+            return decorators[-1]
+        return None
+
+    def pre_decorated(self, subject: DECORATED_T) -> None:
+        """
+        Hook method called before the subject is decorated.
+        Can be overridden by subclasses to perform additional setup.
+        """
+
+    def post_decorated(self, subject: DECORATED_T) -> None:
+        """
+        Hook method called after the subject has been decorated.
+        Can be overridden by subclasses to perform additional setup.
+        """
+
+    @classmethod
+    def get_all_from_type(cls, subject_type: type, inherit: bool = True) -> list[Self]:
+        """
+        Retrieve all decorators of this type from the given class type.
+        """
+        return resolve_class_decorators(subject_type, cls, inherit)
+
+    @classmethod
+    def get_bound_from_type(
+        cls, subject_type: type, inherit: bool = True, last: bool = False
+    ) -> Self | None:
+        """
+        Retrieve the first or last decorator of this type from the given class type.
+        """
+        return resolve_bound_class_decorators(subject_type, cls, inherit, last=last)
+
+    @classmethod
+    def get_all_from_method(
+        cls, cls_subject_type: type, method_name: str, inherit: bool = True
+    ) -> list[Self]:
+        """
+        Retrieve all decorators of this type from the given method.
+        """
+        return resolve_method_decorators(cls_subject_type, method_name, cls, inherit)
+
+    @classmethod
+    def get_bound_from_method(
+        cls,
+        cls_subject_type: type,
+        method_name: str,
+        inherit: bool = True,
+        last: bool = True,
+    ) -> Self | None:
+        """
+        Retrieve the first or last decorator of this type from the given method.
+        """
+        return resolve_bound_method_decorator(
+            cls_subject_type, method_name, cls, inherit, last=last
+        )
+
+
+def resolve_class_decorators(
+    subject: Any, decorator_cls: type[S], inherit: bool = True
+) -> list[S]:
+    """
+    Resolve decorators for a class or instance, optionally inheriting from base classes.
+    """
+    if not inherit:
+        return decorator_cls.get(subject)
+
+    # If subject is an instance, get its class
+    cls = subject if isinstance(subject, type) else type(subject)
+
+    collected: list[S] = []
+    # Iterate MRO in reverse to apply base class decorators first
+    for base in reversed(cls.mro()):
+        collected.extend(decorator_cls.get(base))
+
+    return collected
+
+
+def resolve_bound_class_decorators(
+    subject: Any, decorator_cls: type[S], inherit: bool = True, last: bool = False
+) -> S | None:
+    """
+    Retrieve the first or last decorator of a given type from a class or instance,
+    optionally inheriting from base classes.
+    """
+    decorators = resolve_class_decorators(subject, decorator_cls, inherit)
+    if not decorators:
+        return None
+    return decorators[-1] if last else decorators[0]
+
+
+def resolve_method_decorators(
+    cls: type,
+    method_name: str,
+    decorator_cls: type[S],
+    inherit: bool = True,
+) -> list[S]:
+    """
+    Resolve decorators for a method, optionally inheriting from base classes.
+    """
+    if not inherit:
+        method = getattr(cls, method_name, None)
+        if method:
+            return decorator_cls.get(method)
+        return []
+
+    collected: list[S] = []
+    # Iterate MRO in reverse to apply base class decorators first
+    for base in reversed(cls.mro()):
+        if method_name in base.__dict__:
+            method = base.__dict__[method_name]
+            # Handle staticmethod/classmethod wrappers if necessary?
+            # Usually decorators are on the underlying function or the wrapper.
+            # getattr(cls, name) returns the bound/unbound method.
+            # base.__dict__[name] returns the raw object (function or descriptor).
+
+            # If it's a staticmethod object, it has no __dict__ usually, but we attach attributes to it?
+            # The decorator runs on the function BEFORE it becomes a staticmethod.
+            # So the attribute should be on the function object.
+
+            # However, when we access it via base.__dict__[method_name], we might get the staticmethod object.
+            # We need to unwrap it if possible.
+
+            if isinstance(method, (staticmethod, classmethod)):
+                method = method.__func__
+
+            collected.extend(decorator_cls.get(method))
+
+    return collected
+
+
+def resolve_bound_method_decorator(
+    cls: type,
+    method_name: str,
+    decorator_cls: type[S],
+    inherit: bool = True,
+    last: bool = False,
+) -> S | None:
+    """
+    Retrieve the first or last decorator of a given type from a method,
+    optionally inheriting from base classes.
+    """
+    decorators = resolve_method_decorators(cls, method_name, decorator_cls, inherit)
+    if not decorators:
+        return None
+    return decorators[-1] if last else decorators[0]

jararaca/reflect/metadata.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from contextlib import contextmanager, suppress
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Generator, Mapping, TypeVar, Union
+
+from jararaca.reflect.decorators import StackableDecorator
+
+DECORATED = TypeVar("DECORATED", bound=Union[Callable[..., Awaitable[Any]], type])
+
+
+@dataclass(frozen=True)
+class TransactionMetadata:
+    value: Any
+    """The value of the metadata."""
+
+    inherited_from_controller: bool
+    """Whether the metadata was inherited from a parent class."""
+
+
+metadata_context: ContextVar[Mapping[str, TransactionMetadata]] = ContextVar(
+    "metadata_context"
+)
+
+
+def get_metadata(key: str) -> TransactionMetadata | None:
+    return metadata_context.get({}).get(key)
+
+
+def get_metadata_value(key: str, default: Any | None = None) -> Any:
+    metadata = get_metadata(key)
+    if metadata is None:
+        return default
+    return metadata.value
+
+
+def get_all_metadata() -> Mapping[str, TransactionMetadata]:
+    return metadata_context.get({})
+
+
+@contextmanager
+def start_transaction_metadata_context(
+    metadata: Mapping[str, TransactionMetadata],
+) -> Generator[None, Any, None]:
+
+    current_metadata = metadata_context.get({})
+
+    token = metadata_context.set({**current_metadata, **metadata})
+    try:
+        yield
+    finally:
+        with suppress(ValueError):
+            metadata_context.reset(token)
+
+
+@contextmanager
+def start_providing_metadata(
+    **metadata: Any,
+) -> Generator[None, Any, None]:
+
+    with start_transaction_metadata_context(
+        {
+            key: TransactionMetadata(value=value, inherited_from_controller=False)
+            for key, value in metadata.items()
+        }
+    ):
+        yield
+
+
+class SetMetadata(StackableDecorator):
+    def __init__(self, key: str, value: Any) -> None:
+        self.key = key
+        self.value = value

jararaca/rpc/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later

jararaca/rpc/http/__init__.py

@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# HTTP RPC Module - Complete REST Client Implementation
+"""
+This module provides a complete REST client implementation with support for:
+- HTTP method decorators (@Get, @Post, @Put, @Patch, @Delete)
+- Request parameter decorators (@Query, @Header, @PathParam, @Body, @FormData, @File)
+- Configuration decorators (@Timeout, @Retry, @ContentType)
+- Authentication middleware (BearerTokenAuth, BasicAuth, ApiKeyAuth)
+- Caching and response middleware
+- Request/response hooks for customization
+"""
+
+from .backends.httpx import HTTPXHttpRPCAsyncBackend
+from .decorators import (  # HTTP Method decorators; Request parameter decorators; Configuration decorators; Client builder and core classes; Authentication classes; Middleware and hooks; Configuration classes; Data structures; Error handlers; Exceptions
+    ApiKeyAuth,
+    AuthenticationMiddleware,
+    BasicAuth,
+    BearerTokenAuth,
+    Body,
+    CacheMiddleware,
+    ContentType,
+    Delete,
+    File,
+    FormData,
+    Get,
+    GlobalHttpErrorHandler,
+    Header,
+    HttpMapping,
+    HttpRpcClientBuilder,
+    HttpRPCRequest,
+    HttpRPCResponse,
+    Patch,
+    PathParam,
+    Post,
+    Put,
+    Query,
+    RequestAttribute,
+    RequestHook,
+    ResponseHook,
+    ResponseMiddleware,
+    RestClient,
+    Retry,
+    RetryConfig,
+    RouteHttpErrorHandler,
+    RPCRequestNetworkError,
+    RPCUnhandleError,
+    Timeout,
+    TimeoutException,
+)
+
+__all__ = [
+    # HTTP Method decorators
+    "Get",
+    "Post",
+    "Put",
+    "Patch",
+    "Delete",
+    # Request parameter decorators
+    "Query",
+    "Header",
+    "PathParam",
+    "Body",
+    "FormData",
+    "File",
+    # Configuration decorators
+    "Timeout",
+    "Retry",
+    "ContentType",
+    # Client builder and core classes
+    "RestClient",
+    "HttpRpcClientBuilder",
+    "HttpMapping",
+    "RequestAttribute",
+    # Authentication classes
+    "BearerTokenAuth",
+    "BasicAuth",
+    "ApiKeyAuth",
+    "AuthenticationMiddleware",
+    # Middleware and hooks
+    "CacheMiddleware",
+    "ResponseMiddleware",
+    "RequestHook",
+    "ResponseHook",
+    # Configuration classes
+    "RetryConfig",
+    # Data structures
+    "HttpRPCRequest",
+    "HttpRPCResponse",
+    # Error handlers
+    "GlobalHttpErrorHandler",
+    "RouteHttpErrorHandler",
+    # Exceptions
+    "RPCRequestNetworkError",
+    "RPCUnhandleError",
+    "TimeoutException",
+    # Backend
+    "HTTPXHttpRPCAsyncBackend",
+]

jararaca/rpc/http/backends/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# HTTP RPC Backends
+"""
+Backend implementations for HTTP RPC clients.
+"""
+
+from .httpx import HTTPXHttpRPCAsyncBackend
+
+__all__ = [
+    "HTTPXHttpRPCAsyncBackend",
+]