jararaca 0.3.11a16__py3-none-any.whl → 0.4.0a19__py3-none-any.whl

jararaca/presentation/websocket/types.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 from jararaca.presentation.websocket.base_types import WebSocketMessageBase
 from jararaca.presentation.websocket.context import use_ws_message_sender
 

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
@@ -85,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:
 
@@ -103,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:
@@ -222,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
@@ -236,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(
@@ -246,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

@@ -1,24 +1,28 @@
+# 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 ControllerInstanceMetadata, SetMetadata
+from jararaca.reflect.metadata import SetMetadata, TransactionMetadata
 
 
 @dataclass(frozen=True)
 class ControllerReflect:
 
     controller_class: Type[Any]
-    metadata: Mapping[str, ControllerInstanceMetadata]
+    metadata: Mapping[str, TransactionMetadata]
 
 
 @dataclass(frozen=True)
 class ControllerMemberReflect:
     controller_reflect: ControllerReflect
     member_function: Callable[..., Any]
-    metadata: Mapping[str, ControllerInstanceMetadata]
+    metadata: Mapping[str, TransactionMetadata]
 
 
 def inspect_controller(
@@ -37,8 +41,8 @@ def inspect_controller(
 
     controller_metadata_map = frozendict(
         {
-            metadata.key: ControllerInstanceMetadata(
-                value=metadata.value, inherited=False
+            metadata.key: TransactionMetadata(
+                value=metadata.value, inherited_from_controller=False
             )
             for metadata in controller_metadata_list
         }
@@ -55,21 +59,23 @@ def inspect_controller(
             metadata=frozendict(
                 {
                     **{
-                        key: ControllerInstanceMetadata(
-                            value=value.value, inherited=True
+                        key: TransactionMetadata(
+                            value=value.value, inherited_from_controller=True
                         )
                         for key, value in controller_metadata_map.items()
                     },
                     **{
-                        metadata.key: ControllerInstanceMetadata(
-                            value=metadata.value, inherited=False
+                        metadata.key: TransactionMetadata(
+                            value=metadata.value, inherited_from_controller=False
                         )
                         for metadata in SetMetadata.get(member)
                     },
                 }
             ),
         )
-        for name, member in inspect.getmembers(controller, predicate=inspect.isfunction)
+        for name, member in inspect.getmembers_static(
+            controller, predicate=inspect.isfunction
+        )
     }
 
     return controller_reflect, members

jararaca/reflect/decorators.py

@@ -0,0 +1,252 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Callable, Generic, Self, TypedDict, TypeVar, cast
+
+FUNC_OR_TYPE_T = Callable[..., Any] | type
+
+DECORATED_T = TypeVar("DECORATED_T", bound="FUNC_OR_TYPE_T")
+
+
+S = TypeVar("S", bound="BaseStackableDecorator")
+
+
+class DecoratorMetadata(TypedDict):
+    decorators: "list[BaseStackableDecorator]"
+    decorators_by_type: "dict[Any, list[BaseStackableDecorator]]"
+
+
+class BaseStackableDecorator:
+    _ATTR_NAME: str = "__jararaca_stackable_decorator__"
+
+    def __call__(self, subject: Any) -> Any:
+        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: "BaseStackableDecorator") -> 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: FUNC_OR_TYPE_T) -> None:
+        """
+        Hook method called before the subject is decorated.
+        Can be overridden by subclasses to perform additional setup.
+        """
+
+    def post_decorated(self, subject: FUNC_OR_TYPE_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
+        )
+
+
+class StackableDecorator(BaseStackableDecorator):
+
+    def __call__(self, subject: DECORATED_T) -> DECORATED_T:
+        return cast(DECORATED_T, super().__call__(subject))
+
+
+class GenericStackableDecorator(BaseStackableDecorator, Generic[DECORATED_T]):
+
+    def __call__(self, subject: DECORATED_T) -> DECORATED_T:
+        return cast(DECORATED_T, super().__call__(subject))
+
+
+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/helpers.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+from typing import TYPE_CHECKING, get_args, get_origin
+
+if TYPE_CHECKING:
+    from types import GenericAlias
+
+    from typing_extensions import TypeIs
+
+
+def is_generic_alias(subject: object) -> "TypeIs[GenericAlias]":
+    origin = get_origin(subject)
+    args = get_args(subject)
+
+    return origin is not None and len(args) > 0

jararaca/reflect/metadata.py

@@ -1,23 +1,32 @@
+# 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, Mapping, TypeVar, Union, cast
+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
-class ControllerInstanceMetadata:
+@dataclass(frozen=True)
+class TransactionMetadata:
     value: Any
-    inherited: bool
+    """The value of the metadata."""
+
+    inherited_from_controller: bool
+    """Whether the metadata was inherited from a parent class."""
 
 
-metadata_context: ContextVar[Mapping[str, ControllerInstanceMetadata]] = ContextVar(
+metadata_context: ContextVar[Mapping[str, TransactionMetadata]] = ContextVar(
     "metadata_context"
 )
 
 
-def get_metadata(key: str) -> ControllerInstanceMetadata | None:
+def get_metadata(key: str) -> TransactionMetadata | None:
     return metadata_context.get({}).get(key)
 
 
@@ -28,12 +37,14 @@ def get_metadata_value(key: str, default: Any | None = None) -> Any:
     return metadata.value
 
 
-def get_all_metadata() -> Mapping[str, ControllerInstanceMetadata]:
+def get_all_metadata() -> Mapping[str, TransactionMetadata]:
     return metadata_context.get({})
 
 
 @contextmanager
-def provide_metadata(metadata: Mapping[str, ControllerInstanceMetadata]) -> Any:
+def start_transaction_metadata_context(
+    metadata: Mapping[str, TransactionMetadata],
+) -> Generator[None, Any, None]:
 
     current_metadata = metadata_context.get({})
 
@@ -45,23 +56,21 @@ def provide_metadata(metadata: Mapping[str, ControllerInstanceMetadata]) -> Any:
             metadata_context.reset(token)
 
 
-class SetMetadata:
+@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
-
-    METATADA_LIST = "__metadata_list__"
-
-    @staticmethod
-    def register_metadata(cls: DECORATED, value: "SetMetadata") -> None:
-        metadata_list = getattr(cls, SetMetadata.METATADA_LIST, [])
-        metadata_list.append(value)
-        setattr(cls, SetMetadata.METATADA_LIST, metadata_list)
-
-    @staticmethod
-    def get(cls: DECORATED) -> "list[SetMetadata]":
-        return cast(list[SetMetadata], getattr(cls, SetMetadata.METATADA_LIST, []))
-
-    def __call__(self, cls: DECORATED) -> DECORATED:
-        SetMetadata.register_metadata(cls, self)
-        return cls

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,
+    RouteHttpErrorHandler,
+    RPCRequestNetworkError,
+    RPCRetryPolicy,
+    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
+    "RPCRetryPolicy",
+    # 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",
+]