jararaca 0.4.0a5__py3-none-any.whl → 0.4.0a19__py3-none-any.whl

jararaca/microservice.py

@@ -59,6 +59,8 @@ class MessageBusTransactionData:
     topic: str
     message: MessageOf[Message]
     message_type: Type[Message]
+    message_id: str | None = field(default=None)
+    processing_attempt: int = field(default=0)
     context_type: Literal["message_bus"] = "message_bus"
 
 
@@ -309,7 +311,7 @@ class Container:
         self.register(instance, bind_to)
         return cast(T, instance)
 
-    def register(self, instance: T, bind_to: Any) -> None:
+    def register(self, instance: Any, bind_to: Any) -> None:
         self.instances_map[bind_to] = instance
 
     def get_by_type(self, token: Type[T]) -> T:

jararaca/observability/providers/otel.py

@@ -4,7 +4,7 @@
 
 import logging
 from contextlib import asynccontextmanager, contextmanager
-from typing import Any, AsyncGenerator, Generator, Literal, Protocol
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Generator, Literal, Protocol
 
 from opentelemetry import metrics, trace
 from opentelemetry._logs import set_logger_provider
@@ -49,6 +49,10 @@ from jararaca.observability.decorators import (
 )
 from jararaca.observability.interceptor import ObservabilityProvider
 
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span as _Span
+    from typing_extensions import TypeIs
+
 tracer: trace.Tracer = trace.get_tracer(__name__)
 
 
@@ -82,11 +86,13 @@ def extract_context_attributes(ctx: AppTransactionContext) -> dict[str, Any]:
         }
     elif tx_data.context_type == "message_bus":
         extra_attributes = {
+            "bus.message.id": tx_data.message_id,
             "bus.message.name": tx_data.message_type.__qualname__,
             "bus.message.module": tx_data.message_type.__module__,
             "bus.message.category": tx_data.message_type.MESSAGE_CATEGORY,
             "bus.message.type": tx_data.message_type.MESSAGE_TYPE,
             "bus.message.topic": tx_data.message_type.MESSAGE_TOPIC,
+            "bus.message.processing_attempt": tx_data.processing_attempt,
         }
     elif tx_data.context_type == "websocket":
         extra_attributes = {
@@ -190,13 +196,13 @@ class OtelTracingContextProviderFactory(TracingContextProviderFactory):
 
     @asynccontextmanager
     async def root_setup(
-        self, app_tx_ctx: AppTransactionContext
+        self, app_context: AppTransactionContext
     ) -> AsyncGenerator[None, None]:
 
         title: str = "Unmapped App Context Execution"
         headers: dict[str, Any] = {}
-        tx_data = app_tx_ctx.transaction_data
-        extra_attributes = extract_context_attributes(app_tx_ctx)
+        tx_data = app_context.transaction_data
+        extra_attributes = extract_context_attributes(app_context)
 
         if tx_data.context_type == "http":
             headers = dict(tx_data.request.headers)
@@ -206,7 +212,7 @@ class OtelTracingContextProviderFactory(TracingContextProviderFactory):
             ].decode(errors="ignore")
 
         elif tx_data.context_type == "message_bus":
-            title = f"Message Bus {tx_data.topic}"
+            title = f"Att#{tx_data.processing_attempt} Message Bus {tx_data.topic}"
             headers = use_implicit_headers() or {}
 
         elif tx_data.context_type == "websocket":
@@ -242,12 +248,12 @@ class OtelTracingContextProviderFactory(TracingContextProviderFactory):
         ) as root_span:
             cx = root_span.get_span_context()
             span_traceparent_id = hex(cx.trace_id)[2:].rjust(32, "0")
-            if app_tx_ctx.transaction_data.context_type == "http":
-                app_tx_ctx.transaction_data.request.scope[TRACEPARENT_KEY] = (
+            if app_context.transaction_data.context_type == "http":
+                app_context.transaction_data.request.scope[TRACEPARENT_KEY] = (
                     span_traceparent_id
                 )
-            elif app_tx_ctx.transaction_data.context_type == "websocket":
-                app_tx_ctx.transaction_data.websocket.scope[TRACEPARENT_KEY] = (
+            elif app_context.transaction_data.context_type == "websocket":
+                app_context.transaction_data.websocket.scope[TRACEPARENT_KEY] = (
                     span_traceparent_id
                 )
             tracing_headers: ImplicitHeaders = {}
@@ -262,6 +268,16 @@ class LoggerHandlerCallback(Protocol):
     def __call__(self, logger_handler: logging.Handler) -> None: ...
 
 
+class SpanWithName(Protocol):
+
+    @property
+    def name(self) -> str: ...
+
+
+def is_span_with_name(span: Any) -> "TypeIs[SpanWithName]":
+    return hasattr(span, "name")
+
+
 class CustomLoggingHandler(LoggingHandler):
 
     def _translate(self, record: logging.LogRecord) -> dict[str, Any]:
@@ -270,14 +286,16 @@ class CustomLoggingHandler(LoggingHandler):
             data = super()._translate(record)
             extra_attributes = extract_context_attributes(ctx)
 
-            current_span = trace.get_current_span()
+            current_span: "_Span" = trace.get_current_span()
 
             data["attributes"] = {
                 **data.get("attributes", {}),
                 **extra_attributes,
                 **(
                     {
-                        "span_name": current_span.name,
+                        "span_name": (
+                            current_span.name if is_span_with_name(current_span) else ""
+                        ),
                     }
                     if hasattr(current_span, "name")
                     and current_span.is_recording() is False
@@ -298,7 +316,7 @@ class OtelObservabilityProvider(ObservabilityProvider):
         logs_exporter: LogExporter,
         span_exporter: SpanExporter,
         meter_exporter: MeterExporter,
-        logging_handler_callback: LoggerHandlerCallback = lambda _: None,
+        logging_handler_callback: LoggerHandlerCallback = lambda logger_handler: None,
         meter_export_interval: int = 5000,
     ) -> None:
         self.app_name = app_name
@@ -356,7 +374,7 @@ class OtelObservabilityProvider(ObservabilityProvider):
     def from_url(
         app_name: str,
         url: str,
-        logging_handler_callback: LoggerHandlerCallback = lambda _: None,
+        logging_handler_callback: LoggerHandlerCallback = lambda logger_handler: None,
         meter_export_interval: int = 5000,
     ) -> "OtelObservabilityProvider":
         """

jararaca/persistence/base.py

@@ -43,7 +43,7 @@ BASED_BASE_ENTITY_T = TypeVar("BASED_BASE_ENTITY_T", bound="BaseEntity")
 class BaseEntity(AsyncAttrs, DeclarativeBase):
 
     @classmethod
-    def from_basemodel(cls, mutation: T_BASEMODEL) -> "Self":
+    def from_basemodel(cls, mutation: BaseModel) -> "Self":
         intersection = set(cls.__annotations__.keys()) & set(
             mutation.__class__.model_fields.keys()
         )

jararaca/persistence/utilities.py

@@ -321,6 +321,11 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
             | Select[Tuple[QUERY_ENTITY_T]]
             | None
         ) = None,
+        final_listing_statement: (
+            Callable[[Select[Tuple[QUERY_ENTITY_T]]], Select[Tuple[QUERY_ENTITY_T]]]
+            | None
+        ) = None,
+        total_type: Literal["total_over", "count_subquery"] = "total_over",
     ) -> "Paginated[QUERY_ENTITY_T]":
         """
         Executes a query with the provided filter and interceptors.
@@ -333,9 +338,9 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
 
         initial_statement = self.base_statement or select(self.entity_type)
 
-        if base_statement and callable(base_statement):
+        if base_statement is not None and callable(base_statement):
             initial_statement = base_statement(initial_statement)
-        elif base_statement and isinstance(base_statement, Select):
+        elif base_statement is not None and isinstance(base_statement, Select):
             initial_statement = base_statement
 
         tier_one_filtered_query = self.generate_filtered_query(
@@ -362,32 +367,50 @@ class QueryOperations(Generic[QUERY_FILTER_T, QUERY_ENTITY_T]):
                 )
             )
 
-        paginated_query = tier_two_filtered_query.add_columns(
-            func.count().over().label("total_count")
-        )
-        paginated_query = paginated_query.limit(filter.page_size).offset(
-            (filter.page) * filter.page_size
-        )
+        if final_listing_statement is not None:
+            tier_two_filtered_query = final_listing_statement(tier_two_filtered_query)
 
-        result = await self.session.execute(paginated_query)
-        result = self.judge_unique(result)
-        rows = result.all()
+        if total_type == "total_over":
+            # Use window function for total count (single query)
+            paginated_query = tier_two_filtered_query.add_columns(
+                func.count().over().label("total_count")
+            )
+            paginated_query = paginated_query.limit(filter.page_size).offset(
+                (filter.page) * filter.page_size
+            )
 
-        if rows:
-            unpaginated_total = rows[0].total_count
-            result_scalars = [row[0] for row in rows]
-        else:
-            result_scalars = []
-            if filter.page == 0:
-                unpaginated_total = 0
+            result = await self.session.execute(paginated_query)
+            result = self.judge_unique(result)
+            rows = result.all()
+
+            if rows:
+                unpaginated_total = rows[0].total_count
+                result_scalars = [row[0] for row in rows]
             else:
-                unpaginated_total = (
-                    await self.session.execute(
-                        select(func.count()).select_from(
-                            tier_two_filtered_query.subquery()
-                        )
+                result_scalars = []
+                unpaginated_total = 0
+        else:  # total_type == "count_subquery"
+            # Use separate count query (two queries)
+            paginated_query = tier_two_filtered_query.limit(filter.page_size).offset(
+                (filter.page) * filter.page_size
+            )
+
+            result = await self.session.execute(paginated_query)
+            result = self.judge_unique(result)
+            result_scalars = list(result.scalars())
+
+            # Always fetch total with separate query
+            unpaginated_total = (
+                await self.session.execute(
+                    tier_two_filtered_query.with_only_columns(
+                        func.count(self.entity_type.id)
+                    ).order_by(None)
+                    if issubclass(self.entity_type, IdentifiableEntity)
+                    else select(func.count()).select_from(
+                        tier_two_filtered_query.subquery()
                     )
-                ).scalar_one()
+                )
+            ).scalar_one()
 
         return Paginated(
             items=result_scalars,

jararaca/presentation/decorators.py

@@ -20,7 +20,7 @@ from jararaca.reflect.controller_inspect import (
     ControllerMemberReflect,
     inspect_controller,
 )
-from jararaca.reflect.decorators import DECORATED_T, StackableDecorator
+from jararaca.reflect.decorators import FUNC_OR_TYPE_T, StackableDecorator
 
 DECORATED_TYPE = TypeVar("DECORATED_TYPE", bound=Any)
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
@@ -61,11 +61,11 @@ class RestController(StackableDecorator):
             raise Exception("Router factory is not set")
         return self.router_factory
 
-    def post_decorated(self, subject: DECORATED_T) -> None:
+    def post_decorated(self, subject: FUNC_OR_TYPE_T) -> None:
 
         def router_factory(
             lifecycle: AppLifecycle,
-            instance: DECORATED_T,
+            instance: FUNC_OR_TYPE_T,
         ) -> APIRouter:
             assert inspect.isclass(
                 subject

jararaca/reflect/decorators.py

@@ -2,23 +2,25 @@
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Any, Callable, Self, TypedDict, TypeVar, cast
+from typing import Any, Callable, Generic, Self, TypedDict, TypeVar, cast
 
-DECORATED_T = TypeVar("DECORATED_T", bound="Callable[..., Any] | type")
+FUNC_OR_TYPE_T = Callable[..., Any] | type
 
+DECORATED_T = TypeVar("DECORATED_T", bound="FUNC_OR_TYPE_T")
 
-S = TypeVar("S", bound="StackableDecorator")
+
+S = TypeVar("S", bound="BaseStackableDecorator")
 
 
 class DecoratorMetadata(TypedDict):
-    decorators: "list[StackableDecorator]"
-    decorators_by_type: "dict[Any, list[StackableDecorator]]"
+    decorators: "list[BaseStackableDecorator]"
+    decorators_by_type: "dict[Any, list[BaseStackableDecorator]]"
 
 
-class StackableDecorator:
+class BaseStackableDecorator:
     _ATTR_NAME: str = "__jararaca_stackable_decorator__"
 
-    def __call__(self, subject: DECORATED_T) -> DECORATED_T:
+    def __call__(self, subject: Any) -> Any:
         self.pre_decorated(subject)
         self.register(subject, self)
         self.post_decorated(subject)
@@ -45,7 +47,7 @@ class StackableDecorator:
         return None
 
     @classmethod
-    def register(cls, subject: Any, decorator: "StackableDecorator") -> None:
+    def register(cls, subject: Any, decorator: "BaseStackableDecorator") -> None:
         if not cls._ATTR_NAME:
             raise NotImplementedError("Subclasses must define _ATTR_NAME")
 
@@ -95,13 +97,13 @@ class StackableDecorator:
             return decorators[-1]
         return None
 
-    def pre_decorated(self, subject: DECORATED_T) -> 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: DECORATED_T) -> None:
+    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.
@@ -148,6 +150,18 @@ class StackableDecorator:
         )
 
 
+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]:

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/rpc/http/__init__.py

@@ -43,9 +43,9 @@ from .decorators import (  # HTTP Method decorators; Request parameter decorator
     ResponseMiddleware,
     RestClient,
     Retry,
-    RetryConfig,
     RouteHttpErrorHandler,
     RPCRequestNetworkError,
+    RPCRetryPolicy,
     RPCUnhandleError,
     Timeout,
     TimeoutException,
@@ -85,7 +85,7 @@ __all__ = [
     "RequestHook",
     "ResponseHook",
     # Configuration classes
-    "RetryConfig",
+    "RPCRetryPolicy",
     # Data structures
     "HttpRPCRequest",
     "HttpRPCResponse",

jararaca/rpc/http/decorators.py

@@ -27,7 +27,8 @@ from jararaca.reflect.decorators import StackableDecorator
 
 logger = logging.getLogger(__name__)
 
-DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Awaitable[Any]])
+FUNC_T = Callable[..., Awaitable[Any]]
+DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=FUNC_T)
 DECORATED_CLASS = TypeVar("DECORATED_CLASS", bound=Any)
 
 
@@ -143,11 +144,11 @@ class Timeout:
         return func
 
     @staticmethod
-    def get(func: DECORATED_FUNC) -> Optional["Timeout"]:
+    def get(func: FUNC_T) -> Optional["Timeout"]:
         return getattr(func, Timeout.TIMEOUT_ATTR, None)
 
 
-class RetryConfig:
+class RPCRetryPolicy:
     """Configuration for retry behavior"""
 
     def __init__(
@@ -166,7 +167,7 @@ class Retry:
 
     RETRY_ATTR = "__request_retry__"
 
-    def __init__(self, config: RetryConfig):
+    def __init__(self, config: RPCRetryPolicy):
         self.config = config
 
     def __call__(self, func: DECORATED_FUNC) -> DECORATED_FUNC:
@@ -174,7 +175,7 @@ class Retry:
         return func
 
     @staticmethod
-    def get(func: DECORATED_FUNC) -> Optional["Retry"]:
+    def get(func: FUNC_T) -> Optional["Retry"]:
         return getattr(func, Retry.RETRY_ATTR, None)
 
 
@@ -191,7 +192,7 @@ class ContentType:
         return func
 
     @staticmethod
-    def get(func: DECORATED_FUNC) -> Optional["ContentType"]:
+    def get(func: FUNC_T) -> Optional["ContentType"]:
         return getattr(func, ContentType.CONTENT_TYPE_ATTR, None)
 
 
@@ -390,7 +391,7 @@ class HttpRpcClientBuilder:
         self._response_hooks = response_hooks
 
     async def _execute_with_retry(
-        self, request: HttpRPCRequest, retry_config: Optional[RetryConfig]
+        self, request: HttpRPCRequest, retry_config: Optional[RPCRetryPolicy]
     ) -> HttpRPCResponse:
         """Execute request with retry logic"""
         if not retry_config:
@@ -660,7 +661,7 @@ __all__ = [
     "FormData",
     "File",
     "Timeout",
-    "RetryConfig",
+    "RPCRetryPolicy",
     "Retry",
     "ContentType",
     "RestClient",
@@ -679,7 +680,6 @@ __all__ = [
     "BasicAuth",
     "ApiKeyAuth",
     "CacheMiddleware",
-    "TracedRequestMiddleware",
     "GlobalHttpErrorHandler",
     "RouteHttpErrorHandler",
     "HandleHttpErrorCallback",

jararaca/scheduler/beat_worker.py

@@ -43,7 +43,7 @@ from jararaca.scheduler.decorators import (
 )
 from jararaca.scheduler.types import DelayedMessageData
 from jararaca.utils.rabbitmq_utils import RabbitmqUtils
-from jararaca.utils.retry import RetryConfig, retry_with_backoff
+from jararaca.utils.retry import RetryPolicy, retry_with_backoff
 
 logger = logging.getLogger(__name__)
 
@@ -168,7 +168,7 @@ class _RabbitMQBrokerDispatcher(_MessageBrokerDispatcher):
 
         return await retry_with_backoff(
             _establish_connection,
-            retry_config=self.config.connection_retry_config,
+            retry_policy=self.config.connection_retry_config,
             retry_exceptions=(
                 AMQPConnectionError,
                 ConnectionError,
@@ -189,7 +189,7 @@ class _RabbitMQBrokerDispatcher(_MessageBrokerDispatcher):
 
         return await retry_with_backoff(
             _establish_channel,
-            retry_config=self.config.connection_retry_config,
+            retry_policy=self.config.connection_retry_config,
             retry_exceptions=(
                 AMQPConnectionError,
                 AMQPChannelError,
@@ -219,7 +219,7 @@ class _RabbitMQBrokerDispatcher(_MessageBrokerDispatcher):
         try:
             await retry_with_backoff(
                 _dispatch,
-                retry_config=self.config.dispatch_retry_config,
+                retry_policy=self.config.dispatch_retry_config,
                 retry_exceptions=(
                     AMQPConnectionError,
                     AMQPChannelError,
@@ -261,13 +261,13 @@ class _RabbitMQBrokerDispatcher(_MessageBrokerDispatcher):
                     aio_pika.Message(
                         body=delayed_message.payload,
                     ),
-                    routing_key=f"{delayed_message.message_topic}.",
+                    routing_key=f"{delayed_message.message_topic}.#",
                 )
 
         try:
             await retry_with_backoff(
                 _dispatch,
-                retry_config=self.config.dispatch_retry_config,
+                retry_policy=self.config.dispatch_retry_config,
                 retry_exceptions=(
                     AMQPConnectionError,
                     AMQPChannelError,
@@ -306,7 +306,7 @@ class _RabbitMQBrokerDispatcher(_MessageBrokerDispatcher):
             logger.debug("Initializing RabbitMQ connection...")
             await retry_with_backoff(
                 _initialize,
-                retry_config=self.config.connection_retry_config,
+                retry_policy=self.config.connection_retry_config,
                 retry_exceptions=(
                     AMQPConnectionError,
                     AMQPChannelError,
@@ -447,8 +447,8 @@ def _get_message_broker_dispatcher_from_url(
 class BeatWorkerConfig:
     """Configuration for beat worker connection resilience"""
 
-    connection_retry_config: RetryConfig = field(
-        default_factory=lambda: RetryConfig(
+    connection_retry_config: RetryPolicy = field(
+        default_factory=lambda: RetryPolicy(
             max_retries=10,
             initial_delay=2.0,
             max_delay=60.0,
@@ -456,8 +456,8 @@ class BeatWorkerConfig:
             jitter=True,
         )
     )
-    dispatch_retry_config: RetryConfig = field(
-        default_factory=lambda: RetryConfig(
+    dispatch_retry_config: RetryPolicy = field(
+        default_factory=lambda: RetryPolicy(
             max_retries=3,
             initial_delay=1.0,
             max_delay=10.0,
@@ -561,7 +561,7 @@ class BeatWorker:
 
         # Ensure we have a healthy connection before starting the main loop
         if (
-            hasattr(self.broker, "connection_healthy")
+            isinstance(self.broker, _RabbitMQBrokerDispatcher)
             and not self.broker.connection_healthy
         ):
             logger.error("Connection not healthy at start of processing loop. Exiting.")
@@ -570,7 +570,7 @@ class BeatWorker:
         while not self.shutdown_event.is_set():
             # Check connection health before processing scheduled actions
             if (
-                hasattr(self.broker, "connection_healthy")
+                isinstance(self.broker, _RabbitMQBrokerDispatcher)
                 and not self.broker.connection_healthy
             ):
                 logger.error("Broker connection is not healthy. Exiting.")
@@ -729,7 +729,7 @@ class BeatWorker:
 
             # Check if broker connection is healthy
             if (
-                hasattr(self.broker, "connection_healthy")
+                isinstance(self.broker, _RabbitMQBrokerDispatcher)
                 and self.broker.connection_healthy
             ):
                 logger.debug("Broker connection is healthy")

jararaca/tools/typescript/decorators.py

@@ -67,11 +67,11 @@ class SplitInputOutput(StackableDecorator):
         pass
 
     @staticmethod
-    def is_split_model(cls: type) -> bool:
+    def is_split_model(cls_type: type) -> bool:
         """
         Check if the Pydantic model is marked for split interface generation.
         """
-        return SplitInputOutput.get_last(cls) is not None
+        return SplitInputOutput.get_last(cls_type) is not None
 
 
 class ExposeType:
@@ -106,11 +106,11 @@ class ExposeType:
         return cls
 
     @staticmethod
-    def is_exposed_type(cls: type) -> bool:
+    def is_exposed_type(cls_type: type) -> bool:
         """
         Check if the type is marked for explicit exposure.
         """
-        return getattr(cls, ExposeType.METADATA_KEY, False)
+        return getattr(cls_type, ExposeType.METADATA_KEY, False)
 
     @staticmethod
     def get_all_exposed_types() -> set[type]:

jararaca/tools/typescript/interface_parser.py

@@ -23,6 +23,7 @@ from typing import (
     Literal,
     Type,
     TypeVar,
+    cast,
     get_origin,
 )
 from uuid import UUID
@@ -554,7 +555,8 @@ def parse_single_typescript_interface(
     mapped_types.update(inherited_classes)
 
     if Enum in inherited_classes:
-        enum_values = sorted([(x._name_, x.value) for x in basemodel_type])
+        enum_casted = cast(Type[Enum], basemodel_type)
+        enum_values = sorted([(x._name_, x.value) for x in enum_casted])
         return (
             set(),
             f"export enum {basemodel_type.__name__}{interface_suffix} {{\n"