jararaca 0.3.11a4__py3-none-any.whl → 0.3.11a5__py3-none-any.whl

jararaca/observability/interceptor.py

@@ -2,9 +2,9 @@ from contextlib import asynccontextmanager
 from typing import AsyncContextManager, AsyncGenerator, Protocol
 
 from jararaca.microservice import (
-    AppContext,
     AppInterceptor,
     AppInterceptorWithLifecycle,
+    AppTransactionContext,
     Container,
     Microservice,
 )
@@ -32,7 +32,9 @@ class ObservabilityInterceptor(AppInterceptor, AppInterceptorWithLifecycle):
         self.observability_provider = observability_provider
 
     @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def intercept(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
 
         async with self.observability_provider.tracing_provider.root_setup(app_context):
 

jararaca/observability/providers/otel.py

@@ -23,7 +23,7 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
 
-from jararaca.microservice import AppContext, Container, Microservice
+from jararaca.microservice import AppTransactionContext, Container, Microservice
 from jararaca.observability.decorators import (
     TracingContextProvider,
     TracingContextProviderFactory,
@@ -36,7 +36,7 @@ tracer: trace.Tracer = trace.get_tracer(__name__)
 
 class OtelTracingContextProvider(TracingContextProvider):
 
-    def __init__(self, app_context: AppContext) -> None:
+    def __init__(self, app_context: AppTransactionContext) -> None:
         self.app_context = app_context
 
     @contextmanager
@@ -52,22 +52,26 @@ class OtelTracingContextProvider(TracingContextProvider):
 
 class OtelTracingContextProviderFactory(TracingContextProviderFactory):
 
-    def provide_provider(self, app_context: AppContext) -> TracingContextProvider:
+    def provide_provider(
+        self, app_context: AppTransactionContext
+    ) -> TracingContextProvider:
         return OtelTracingContextProvider(app_context)
 
     @asynccontextmanager
-    async def root_setup(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def root_setup(
+        self, app_tx_ctx: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
 
         title: str = "Unmapped App Context Execution"
         headers = {}
+        tx_data = app_tx_ctx.transaction_data
+        if tx_data.context_type == "http":
 
-        if app_context.context_type == "http":
-
-            headers = dict(app_context.request.headers)
-            title = f"HTTP {app_context.request.method} {app_context.request.url}"
+            headers = dict(tx_data.request.headers)
+            title = f"HTTP {tx_data.request.method} {tx_data.request.url}"
 
-        elif app_context.context_type == "message_bus":
-            title = f"Message Bus {app_context.topic}"
+        elif tx_data.context_type == "message_bus":
+            title = f"Message Bus {tx_data.topic}"
 
         carrier = {
             key: value

jararaca/persistence/interceptors/aiosqa_interceptor.py

@@ -11,15 +11,18 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.ext.asyncio.engine import AsyncEngine
 
-from jararaca.microservice import AppContext, AppInterceptor
+from jararaca.microservice import AppInterceptor, AppTransactionContext
+from jararaca.reflect.metadata import SetMetadata, get_metadata_value
 
-ctx_default_connection_name: ContextVar[str] = ContextVar("ctx_default_connection_name")
+DEFAULT_CONNECTION_NAME = "default"
+
+ctx_default_connection_name: ContextVar[str] = ContextVar(
+    "ctx_default_connection_name", default=DEFAULT_CONNECTION_NAME
+)
 
 
 def ensure_name(name: str | None) -> str:
-    if name is None:
-        return ctx_default_connection_name.get()
-    return name
+    return ctx_default_connection_name.get()
 
 
 @dataclass
@@ -37,7 +40,10 @@ def providing_session(
     tx: AsyncSessionTransaction,
     connection_name: str | None = None,
 ) -> Generator[None, Any, None]:
-
+    """
+    Context manager to provide a session and transaction for a specific connection name.
+    If no connection name is provided, it uses the default connection name from the context variable.
+    """
     connection_name = ensure_name(connection_name)
     current_map = ctx_session_map.get({})
 
@@ -52,6 +58,12 @@ def providing_session(
             ctx_session_map.reset(token)
 
 
+provide_session = providing_session
+"""
+Alias for `providing_session` to maintain backward compatibility.
+"""
+
+
 @asynccontextmanager
 async def providing_new_session(
     connection_name: str | None = None,
@@ -70,7 +82,9 @@ def use_session(connection_name: str | None = None) -> AsyncSession:
     connection_name = ensure_name(connection_name)
     current_map = ctx_session_map.get({})
     if connection_name not in current_map:
-        raise ValueError(f"Session not found for connection {connection_name}")
+        raise ValueError(
+            f'Session not found for connection "{connection_name}" in context. Check if your interceptor is correctly set up.'
+        )
 
     return current_map[connection_name].session
 
@@ -102,10 +116,60 @@ def use_transaction(connection_name: str | None = None) -> AsyncSessionTransacti
 class AIOSQAConfig:
     url: str | AsyncEngine
     connection_name: str
-
-    def __init__(self, url: str | AsyncEngine, connection_name: str = "default"):
+    inject_default: bool
+
+    def __init__(
+        self,
+        url: str | AsyncEngine,
+        connection_name: str = DEFAULT_CONNECTION_NAME,
+        inject_default: bool = True,
+    ):
         self.url = url
         self.connection_name = connection_name
+        self.inject_default = inject_default
+
+
+INJECT_CONNECTION_METADATA = "inject_connection_metadata_{connection_name}"
+
+
+def set_inject_connection(
+    inject: bool, connection_name: str = DEFAULT_CONNECTION_NAME
+) -> SetMetadata:
+    """
+    Set whether to inject the connection metadata for the given connection name.
+    This is useful when you want to control whether the connection metadata
+    should be injected into the context or not.
+    """
+
+    return SetMetadata(
+        INJECT_CONNECTION_METADATA.format(connection_name=connection_name), inject
+    )
+
+
+def uses_connection(
+    connection_name: str = DEFAULT_CONNECTION_NAME,
+) -> SetMetadata:
+    """
+    Use connection metadata for the given connection name.
+    This is useful when you want to inject the connection metadata into the context,
+    for example, when you are using a specific connection for a specific operation.
+    """
+    return SetMetadata(
+        INJECT_CONNECTION_METADATA.format(connection_name=connection_name), True
+    )
+
+
+def dnt_uses_connection(
+    connection_name: str = DEFAULT_CONNECTION_NAME,
+) -> SetMetadata:
+    """
+    Do not use connection metadata for the given connection name.
+    This is useful when you want to ensure that the connection metadata is not injected
+    into the context, for example, when you are using a different connection for a specific operation.
+    """
+    return SetMetadata(
+        INJECT_CONNECTION_METADATA.format(connection_name=connection_name), False
+    )
 
 
 class AIOSqlAlchemySessionInterceptor(AppInterceptor):
@@ -121,7 +185,20 @@ class AIOSqlAlchemySessionInterceptor(AppInterceptor):
         self.sessionmaker = async_sessionmaker(self.engine)
 
     @asynccontextmanager
-    async def intercept(self, app_context: AppContext) -> AsyncGenerator[None, None]:
+    async def intercept(
+        self, app_context: AppTransactionContext
+    ) -> AsyncGenerator[None, None]:
+
+        uses_connection_metadata = get_metadata_value(
+            INJECT_CONNECTION_METADATA.format(
+                connection_name=self.config.connection_name
+            ),
+            self.config.inject_default,
+        )
+
+        if not uses_connection_metadata:
+            yield
+            return
 
         async with self.sessionmaker() as session, session.begin() as tx:
             token = ctx_default_connection_name.set(self.config.connection_name)
@@ -134,4 +211,5 @@ class AIOSqlAlchemySessionInterceptor(AppInterceptor):
                     await tx.rollback()
                     raise e
                 finally:
-                    ctx_default_connection_name.reset(token)
+                    with suppress(ValueError):
+                        ctx_default_connection_name.reset(token)

jararaca/presentation/decorators.py

@@ -1,5 +1,7 @@
-import inspect
-from typing import Any, Callable, Literal, Protocol, TypeVar, cast
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import wraps
+from typing import Any, Awaitable, Callable, Literal, Protocol, TypeVar, cast
 
 from fastapi import APIRouter
 from fastapi import Depends as DependsF
@@ -9,6 +11,10 @@ from fastapi.params import Depends
 from jararaca.lifecycle import AppLifecycle
 from jararaca.presentation.http_microservice import HttpMiddleware
 from jararaca.presentation.websocket.decorators import WebSocketEndpoint
+from jararaca.reflect.controller_inspect import (
+    ControllerMemberReflect,
+    inspect_controller,
+)
 
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
 DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
@@ -73,15 +79,15 @@ class RestController:
                 **(self.options or {}),
             )
 
-            members = inspect.getmembers(cls, predicate=inspect.isfunction)
+            controller, members = inspect_controller(cls)
 
             router_members = [
-                (name, mapping)
-                for name, member in members
+                (name, mapping, member)
+                for name, member in members.items()
                 if (
                     mapping := (
-                        HttpMapping.get_http_mapping(member)
-                        or WebSocketEndpoint.get(member)
+                        HttpMapping.get_http_mapping(member.member_function)
+                        or WebSocketEndpoint.get(member.member_function)
                     )
                 )
                 is not None
@@ -89,7 +95,7 @@ class RestController:
 
             router_members.sort(key=lambda x: x[1].order)
 
-            for name, mapping in router_members:
+            for name, mapping, member in router_members:
                 route_dependencies: list[Depends] = []
                 for middlewares_by_hook in UseMiddleware.get_middlewares(
                     getattr(instance, name)
@@ -104,12 +110,18 @@ class RestController:
                 ):
                     route_dependencies.append(DependsF(dependency.dependency))
 
+                instance_method = getattr(instance, name)
+                instance_method = wraps_with_attributes(
+                    instance_method,
+                    controller_member_reflect=member,
+                )
+
                 if isinstance(mapping, HttpMapping):
                     try:
                         router.add_api_route(
                             methods=[mapping.method],
                             path=mapping.path,
-                            endpoint=getattr(instance, name),
+                            endpoint=instance_method,
                             dependencies=route_dependencies,
                             **(mapping.options or {}),
                         )
@@ -120,7 +132,7 @@ class RestController:
                 else:
                     router.add_api_websocket_route(
                         path=mapping.path,
-                        endpoint=getattr(instance, name),
+                        endpoint=instance_method,
                         dependencies=route_dependencies,
                         **(mapping.options or {}),
                     )
@@ -299,3 +311,77 @@ class UseDependency:
     @staticmethod
     def get_dependencies(subject: DECORATED_FUNC) -> list["UseDependency"]:
         return getattr(subject, UseDependency.__DEPENDENCY_ATTR__, [])
+
+
+def wraps_with_member_data(
+    controller_member: ControllerMemberReflect, func: Callable[..., Awaitable[Any]]
+) -> Callable[..., Any]:
+    """
+    A decorator that wraps a function and preserves its metadata.
+    This is useful for preserving metadata when using decorators.
+    """
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+
+        with providing_controller_member(
+            controller_member=controller_member,
+        ):
+
+            return await func(*args, **kwargs)
+
+    # Copy metadata from the original function to the wrapper
+    # for attr in dir(func):
+    #     if not attr.startswith("__"):
+    #         setattr(wrapper, attr, getattr(func, attr))
+
+    return wrapper
+
+
+controller_member_ctxvar = ContextVar[ControllerMemberReflect](
+    "controller_member_ctxvar"
+)
+
+
+@contextmanager
+def providing_controller_member(
+    controller_member: ControllerMemberReflect,
+) -> Any:
+    """
+    Context manager to provide the controller member metadata.
+    This is used to preserve the metadata of the controller member
+    when using decorators.
+    """
+    token = controller_member_ctxvar.set(controller_member)
+    try:
+        yield
+    finally:
+        controller_member_ctxvar.reset(token)
+
+
+def use_controller_member() -> ControllerMemberReflect:
+    """
+    Get the current controller member metadata.
+    This is used to access the metadata of the controller member
+    when using decorators.
+    """
+    return controller_member_ctxvar.get()
+
+
+def wraps_with_attributes(
+    func: Callable[..., Awaitable[Any]], **attributes: Any
+) -> Callable[..., Awaitable[Any]]:
+    """
+    A decorator that wraps a function and preserves its attributes.
+    This is useful for preserving attributes when using decorators.
+    """
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return await func(*args, **kwargs)
+
+    # Copy attributes from the original function to the wrapper
+    for key, value in attributes.items():
+        setattr(wrapper, key, value)
+
+    return wrapper

jararaca/presentation/server.py

@@ -7,9 +7,14 @@ from starlette.types import ASGIApp
 from jararaca.core.uow import UnitOfWorkContextProvider
 from jararaca.di import Container
 from jararaca.lifecycle import AppLifecycle
-from jararaca.microservice import HttpAppContext, WebSocketAppContext
+from jararaca.microservice import (
+    AppTransactionContext,
+    HttpTransactionData,
+    WebSocketTransactionData,
+)
 from jararaca.presentation.decorators import RestController
 from jararaca.presentation.http_microservice import HttpMicroservice
+from jararaca.reflect.controller_inspect import ControllerMemberReflect
 
 
 class HttpAppLifecycle:
@@ -79,10 +84,32 @@ class HttpUowContextProviderDependency:
     async def __call__(
         self, websocket: WebSocket = None, request: Request = None  # type: ignore
     ) -> AsyncGenerator[None, None]:
+        if request:
+            endpoint = request.scope["endpoint"]
+        elif websocket:
+            endpoint = websocket.scope["endpoint"]
+        else:
+            raise ValueError("Either request or websocket must be provided.")
+
+        member = getattr(endpoint, "controller_member_reflect", None)
+
+        if member is None:
+            raise ValueError("The endpoint does not have a controller member reflect.")
+
+        assert isinstance(member, ControllerMemberReflect), (
+            "Expected endpoint.controller_member_reflect to be of type "
+            "ControllerMemberReflect, but got: {}".format(type(member))
+        )
+
         async with self.uow_provider(
-            HttpAppContext(request=request)
-            if request
-            else WebSocketAppContext(websocket=websocket)
+            AppTransactionContext(
+                controller_member_reflect=member,
+                transaction_data=(
+                    HttpTransactionData(request=request)
+                    if request
+                    else WebSocketTransactionData(websocket=websocket)
+                ),
+            )
         ):
             yield
 

jararaca/presentation/websocket/websocket_interceptor.py

@@ -13,9 +13,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 (
@@ -185,7 +185,9 @@ 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]:
 
         staging_ws_messages_sender = StagingWebSocketMessageSender(
             self.connection_manager

jararaca/reflect/controller_inspect.py

@@ -0,0 +1,75 @@
+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
+
+
+@dataclass(frozen=True)
+class ControllerReflect:
+
+    controller_class: Type[Any]
+    metadata: Mapping[str, ControllerInstanceMetadata]
+
+
+@dataclass(frozen=True)
+class ControllerMemberReflect:
+    controller_reflect: ControllerReflect
+    member_function: Callable[..., Any]
+    metadata: Mapping[str, ControllerInstanceMetadata]
+
+
+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: ControllerInstanceMetadata(
+                value=metadata.value, inherited=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: ControllerInstanceMetadata(
+                            value=value.value, inherited=True
+                        )
+                        for key, value in controller_metadata_map.items()
+                    },
+                    **{
+                        metadata.key: ControllerInstanceMetadata(
+                            value=metadata.value, inherited=False
+                        )
+                        for metadata in SetMetadata.get(member)
+                    },
+                }
+            ),
+        )
+        for name, member in inspect.getmembers(controller, predicate=inspect.isfunction)
+    }
+
+    return controller_reflect, members

jararaca/{tools → reflect}/metadata.py

@@ -1,19 +1,39 @@
 from contextlib import contextmanager, suppress
 from contextvars import ContextVar
-from typing import Any, Awaitable, Callable, TypeVar, Union, cast
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping, TypeVar, Union, cast
 
 DECORATED = TypeVar("DECORATED", bound=Union[Callable[..., Awaitable[Any]], type])
 
 
-metadata_context: ContextVar[dict[str, Any]] = ContextVar("metadata_context")
+@dataclass
+class ControllerInstanceMetadata:
+    value: Any
+    inherited: bool
 
 
-def get_metadata(key: str) -> Any | None:
+metadata_context: ContextVar[Mapping[str, ControllerInstanceMetadata]] = ContextVar(
+    "metadata_context"
+)
+
+
+def get_metadata(key: str) -> ControllerInstanceMetadata | 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, ControllerInstanceMetadata]:
+    return metadata_context.get({})
+
+
 @contextmanager
-def provide_metadata(metadata: dict[str, Any]) -> Any:
+def provide_metadata(metadata: Mapping[str, ControllerInstanceMetadata]) -> Any:
 
     current_metadata = metadata_context.get({})
 
@@ -39,7 +59,7 @@ class SetMetadata:
         setattr(cls, SetMetadata.METATADA_LIST, metadata_list)
 
     @staticmethod
-    def get(cls: type) -> "list[SetMetadata]":
+    def get(cls: DECORATED) -> "list[SetMetadata]":
         return cast(list[SetMetadata], getattr(cls, SetMetadata.METATADA_LIST, []))
 
     def __call__(self, cls: DECORATED) -> DECORATED:

jararaca/scheduler/decorators.py

@@ -1,5 +1,11 @@
 import inspect
-from typing import Any, Callable, TypeVar, cast
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, TypeVar, cast
+
+from jararaca.reflect.controller_inspect import (
+    ControllerMemberReflect,
+    inspect_controller,
+)
 
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
 
@@ -66,25 +72,6 @@ class ScheduledAction:
             ScheduledAction, getattr(func, ScheduledAction.SCHEDULED_ACTION_ATTR)
         )
 
-    @staticmethod
-    def get_type_scheduled_actions(
-        instance: Any,
-    ) -> list[tuple[Callable[..., Any], "ScheduledAction"]]:
-
-        members = inspect.getmembers(instance, predicate=inspect.ismethod)
-
-        scheduled_actions: list[tuple[Callable[..., Any], "ScheduledAction"]] = []
-
-        for _, member in members:
-            scheduled_action = ScheduledAction.get_scheduled_action(member)
-
-            if scheduled_action is None:
-                continue
-
-            scheduled_actions.append((member, scheduled_action))
-
-        return scheduled_actions
-
     @staticmethod
     def get_function_id(
         func: Callable[..., Any],
@@ -94,3 +81,44 @@ class ScheduledAction:
         This is used to identify the scheduled action in the message broker.
         """
         return f"{func.__module__}.{func.__qualname__}"
+
+
+@dataclass(frozen=True)
+class ScheduledActionData:
+    spec: ScheduledAction
+    controller_member: ControllerMemberReflect
+    callable: Callable[..., Awaitable[None]]
+
+
+def get_type_scheduled_actions(
+    instance: Any,
+) -> list[ScheduledActionData]:
+
+    _, member_metadata_map = inspect_controller(instance.__class__)
+
+    members = inspect.getmembers(instance, predicate=inspect.ismethod)
+
+    scheduled_actions: list[ScheduledActionData] = []
+
+    for name, member in members:
+        scheduled_action = ScheduledAction.get_scheduled_action(member)
+
+        if scheduled_action is None:
+            continue
+
+        if name not in member_metadata_map:
+            raise Exception(
+                f"Member '{name}' is not a valid controller member in '{instance.__class__.__name__}'"
+            )
+
+        member_metadata = member_metadata_map[name]
+
+        scheduled_actions.append(
+            ScheduledActionData(
+                callable=member,
+                spec=scheduled_action,
+                controller_member=member_metadata,
+            )
+        )
+
+    return scheduled_actions