repid 2.1.2__tar.gz → 2.1.3__tar.gz

{repid-2.1.2 → repid-2.1.3}/.github/workflows/codeql.yml

@@ -38,7 +38,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
       # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

{repid-2.1.2 → repid-2.1.3}/.github/workflows/dependency-review.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: Setup uv
       uses: astral-sh/setup-uv@v7

{repid-2.1.2 → repid-2.1.3}/.github/workflows/docs.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

{repid-2.1.2 → repid-2.1.3}/.github/workflows/mypy.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: Setup uv
       uses: astral-sh/setup-uv@v7

{repid-2.1.2 → repid-2.1.3}/.github/workflows/release.yaml

@@ -15,7 +15,7 @@ jobs:
       id-token: write
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

{repid-2.1.2 → repid-2.1.3}/.github/workflows/tests.yaml

@@ -26,7 +26,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: Setup uv
       uses: astral-sh/setup-uv@v7
@@ -60,7 +60,7 @@ jobs:
       contents: write
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
 
     - name: Setup uv
       uses: astral-sh/setup-uv@v7

{repid-2.1.2 → repid-2.1.3}/.pre-commit-config.yaml

@@ -19,14 +19,14 @@ repos:
   - id: end-of-file-fixer
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.15.15
+  rev: v0.15.18
   hooks:
   - id: ruff-check
     args: [--fix, --exit-non-zero-on-fix]
   - id: ruff-format
 
 - repo: https://github.com/igorshubovych/markdownlint-cli
-  rev: v0.48.0
+  rev: v0.49.0
   hooks:
   - id: markdownlint-fix
     args: [--config=pyproject.toml, --configPointer=/tool/markdownlint]

{repid-2.1.2 → repid-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repid
-Version: 2.1.2
+Version: 2.1.3
 Summary: Repid is a simple, fast, and extensible async task queue framework, with built-in AsyncAPI 3.0 schema generation.
 Project-URL: documentation, https://repid.aleksul.space
 Project-URL: funding, https://github.com/sponsors/aleksul

repid-2.1.3/docs/cookbook/opentelemetry_middleware.md

@@ -0,0 +1,281 @@
+# OpenTelemetry Middleware
+
+[OpenTelemetry](https://opentelemetry.io/) gives you vendor-neutral traces and metrics for your
+Repid producers and actors. This cookbook shows how to configure Repid middlewares that propagate
+trace context through message headers and record message processing and publishing metrics.
+
+## Prerequisites
+
+Install the OpenTelemetry API, SDK, and an exporter. This example uses the OTLP gRPC exporter,
+which works with OpenTelemetry Collector and many observability vendors.
+
+```bash
+pip install repid opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc
+```
+
+If your application already configures OpenTelemetry, keep that setup and only add the Repid
+middlewares below.
+
+## OpenTelemetry Setup
+
+Configure the OpenTelemetry SDK once when your process starts. A worker process and any process that
+publishes Repid messages should both initialize OpenTelemetry. The exact exporter, endpoint,
+resource attributes, sampling, and authentication settings are up to your application and depend
+heavily on your observability infrastructure.
+
+Below is a minimal OTLP gRPC example, not a required Repid configuration.
+
+```python
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+
+def configure_opentelemetry(service_name: str = "repid-worker") -> None:
+    resource = Resource.create({"service.name": service_name})
+
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(tracer_provider)
+
+    metric_reader = PeriodicExportingMetricReader(OTLPMetricExporter())
+    meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+    metrics.set_meter_provider(meter_provider)
+```
+
+## The Middlewares
+
+In total, we will create 4 middlewares: 2 metric reporting middlewares, and
+2 tracing middlewares - each for producer and consumer parts.
+
+When a producer sends a Repid message, the active `traceparent` and `tracestate` headers
+are injected into the message. When a worker consumes that message,
+the actor span continues the same distributed trace.
+
+The span names and attributes follow the
+[OpenTelemetry messaging semantic conventions](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#messaging-attributes).
+
+```python
+from collections.abc import Callable, Coroutine
+from dataclasses import replace
+from time import perf_counter
+from typing import Any, TypeVar
+
+from opentelemetry import context as context_api
+from opentelemetry import metrics, trace
+from opentelemetry.propagate import extract, inject
+from repid import ActorData, MessageData, ReceivedMessageT
+
+T = TypeVar("T")
+
+TRACER = trace.get_tracer(__name__)
+METER = metrics.get_meter(__name__)
+
+# Pick the semantic-convention value for your broker, for example
+# "rabbitmq", "kafka", "aws_sqs", or "gcp_pubsub". If none applies, use a
+# stable low-cardinality custom value.
+MESSAGING_SYSTEM = "rabbitmq"
+
+# Use operation names that match your broker or client terminology.
+PRODUCER_OPERATION_NAME = "send"
+CONSUMER_OPERATION_NAME = "process"
+
+REPID_CONSUMER_MESSAGES = METER.create_counter(
+    name="repid.consumer.messages",
+    unit="{message}",
+    description="The number of messages consumed by Repid actors.",
+)
+REPID_CONSUMER_FAILURES = METER.create_counter(
+    name="repid.consumer.failures",
+    unit="{message}",
+    description="The number of Repid actor message handling failures.",
+)
+REPID_CONSUMER_DURATION = METER.create_histogram(
+    name="repid.consumer.processing.duration",
+    unit="s",
+    description="The time spent handling a consumed Repid message.",
+)
+
+REPID_PRODUCER_MESSAGES = METER.create_counter(
+    name="repid.producer.messages",
+    unit="{message}",
+    description="The number of messages published by Repid producers.",
+)
+REPID_PRODUCER_FAILURES = METER.create_counter(
+    name="repid.producer.failures",
+    unit="{message}",
+    description="The number of Repid producer publish failures.",
+)
+REPID_PRODUCER_DURATION = METER.create_histogram(
+    name="repid.producer.publish.duration",
+    unit="s",
+    description="The time spent publishing a Repid message.",
+)
+
+
+async def consumer_tracing_middleware(
+    call_next: Callable[[ReceivedMessageT, ActorData], Coroutine[Any, Any, T]],
+    message: ReceivedMessageT,
+    actor: ActorData,
+) -> T:
+    span_attributes = {
+        "messaging.system": MESSAGING_SYSTEM,
+        "messaging.destination.name": message.channel,
+        "messaging.operation.type": "process",
+        "messaging.operation.name": CONSUMER_OPERATION_NAME,
+        "repid.actor.name": actor.name,
+        "repid.actor.channel_address": actor.channel_address,
+    }
+    if message.message_id:
+        span_attributes["messaging.message.id"] = message.message_id
+
+    ctx = extract(message.headers or {})
+    token = context_api.attach(ctx)
+    try:
+        with TRACER.start_as_current_span(
+            f"{CONSUMER_OPERATION_NAME} {message.channel}",
+            kind=trace.SpanKind.CONSUMER,
+            attributes=span_attributes,
+        ) as span:
+            try:
+                return await call_next(message, actor)
+            except Exception as exc:
+                span.set_attribute("error.type", type(exc).__name__)
+                raise
+    finally:
+        context_api.detach(token)
+
+
+async def consumer_metrics_middleware(
+    call_next: Callable[[ReceivedMessageT, ActorData], Coroutine[Any, Any, T]],
+    message: ReceivedMessageT,
+    actor: ActorData,
+) -> T:
+    metric_attributes = {
+        "messaging.system": MESSAGING_SYSTEM,
+        "messaging.destination.name": message.channel,
+        "repid.actor.name": actor.name,
+        "repid.actor.channel_address": actor.channel_address,
+    }
+    started_at = perf_counter()
+    REPID_CONSUMER_MESSAGES.add(1, attributes=metric_attributes)
+
+    try:
+        return await call_next(message, actor)
+    except Exception as exc:
+        REPID_CONSUMER_FAILURES.add(
+            1,
+            attributes={**metric_attributes, "error.type": type(exc).__name__},
+        )
+        raise
+    finally:
+        REPID_CONSUMER_DURATION.record(
+            perf_counter() - started_at,
+            attributes=metric_attributes,
+        )
+
+
+async def producer_tracing_middleware(
+    call_next: Callable[
+        [str, MessageData, dict[str, Any] | None],
+        Coroutine[Any, Any, T],
+    ],
+    channel: str,
+    message: MessageData,
+    server_specific_parameters: dict[str, Any] | None,
+) -> T:
+    span_attributes = {
+        "messaging.system": MESSAGING_SYSTEM,
+        "messaging.destination.name": channel,
+        "messaging.operation.type": "send",
+        "messaging.operation.name": PRODUCER_OPERATION_NAME,
+    }
+
+    with TRACER.start_as_current_span(
+        f"{PRODUCER_OPERATION_NAME} {channel}",
+        kind=trace.SpanKind.PRODUCER,
+        attributes=span_attributes,
+    ) as span:
+        headers = dict(message.headers or {})
+        inject(headers)
+        replaced_message = replace(message, headers=headers)
+
+        try:
+            return await call_next(channel, replaced_message, server_specific_parameters)
+        except Exception as exc:
+            span.set_attribute("error.type", type(exc).__name__)
+            raise
+
+
+async def producer_metrics_middleware(
+    call_next: Callable[
+        [str, MessageData, dict[str, Any] | None],
+        Coroutine[Any, Any, T],
+    ],
+    channel: str,
+    message: MessageData,
+    server_specific_parameters: dict[str, Any] | None,
+) -> T:
+    metric_attributes = {
+        "messaging.system": MESSAGING_SYSTEM,
+        "messaging.destination.name": channel,
+    }
+    started_at = perf_counter()
+    REPID_PRODUCER_MESSAGES.add(1, attributes=metric_attributes)
+
+    try:
+        return await call_next(channel, message, server_specific_parameters)
+    except Exception as exc:
+        REPID_PRODUCER_FAILURES.add(
+            1,
+            attributes={**metric_attributes, "error.type": type(exc).__name__},
+        )
+        raise
+    finally:
+        REPID_PRODUCER_DURATION.record(
+            perf_counter() - started_at,
+            attributes=metric_attributes,
+        )
+```
+
+!!! note
+    Keep metric attributes low-cardinality. Channel names, actor names, and error types are usually
+    safe. Message IDs are useful on spans, but should not be added to metrics.
+
+## Registering the Middlewares
+
+Lastly, you need to register those middlewares:
+
+```python
+from repid import Repid, Router
+
+from my_project.observability import configure_opentelemetry
+from my_project.repid_otel import (
+    consumer_metrics_middleware,
+    consumer_tracing_middleware,
+    producer_metrics_middleware,
+    producer_tracing_middleware,
+)
+
+configure_opentelemetry(service_name="repid-worker")
+
+app = Repid(
+    actor_middlewares=[consumer_tracing_middleware, consumer_metrics_middleware],
+    producer_middlewares=[producer_tracing_middleware, producer_metrics_middleware],
+)
+
+router = Router()
+
+
+@router.actor(channel="charge_customer")
+async def charge_customer(customer_id: str) -> None:
+    print(f"Charging {customer_id}")
+
+
+app.include_router(router)
+```

{repid-2.1.2 → repid-2.1.3}/mkdocs.yml

@@ -43,6 +43,7 @@ nav:
   - Middlewares: cookbook/middlewares.md
 - Cookbook:
   - Sentry Middleware: cookbook/sentry_middleware.md
+  - OpenTelemetry Middleware: cookbook/opentelemetry_middleware.md
   - RabbitMQ Retries: cookbook/rabbitmq_retries.md
   - Large Payloads: cookbook/large_payloads.md
 - Extending Repid:
@@ -124,6 +125,7 @@ plugins:
       - cookbook/middlewares.md
       Cookbook:
       - cookbook/sentry_middleware.md
+      - cookbook/opentelemetry_middleware.md
       - cookbook/rabbitmq_retries.md
       - cookbook/large_payloads.md
       Extending Repid:

{repid-2.1.2 → repid-2.1.3}/repid/_runner.py

@@ -8,7 +8,8 @@ from contextlib import suppress
 from functools import partial
 from typing import TYPE_CHECKING, Any
 
-from repid.connections.abc import ServerT, SubscriberT
+from repid.connections.abc import SubscriberT
+from repid.data.actor import ActorExecutionContext
 from repid.health_check_server import HealthCheckStatus
 
 logger = logging.getLogger("repid")
@@ -17,7 +18,6 @@ if TYPE_CHECKING:
     from repid.connections.abc import ReceivedMessageT
     from repid.data.actor import ActorData
     from repid.health_check_server import HealthCheckServer
-    from repid.serializer import SerializerT
 
 
 ActorResultT = Any
@@ -26,14 +26,12 @@ ActorResultT = Any
 async def _actor_execution(
     message: ReceivedMessageT,
     actor: ActorData,
-    server: ServerT,
-    default_serializer: SerializerT,
+    actor_context: ActorExecutionContext,
 ) -> ActorResultT:
     args, kwargs = await actor.converter.convert_inputs(
         message=message,
         actor=actor,
-        server=server,
-        default_serializer=default_serializer,
+        actor_context=actor_context,
     )
     return await actor.fn(*args, **kwargs)
 
@@ -52,23 +50,22 @@ async def _keep_alive_loop(message: ReceivedMessageT, interval: float) -> None:
 async def _run_with_keepalive(
     message: ReceivedMessageT,
     actor: ActorData,
-    server: ServerT,
-    default_serializer: SerializerT,
+    actor_context: ActorExecutionContext,
 ) -> ActorResultT:
     if actor.keep_alive is False:
-        return await _actor_execution(message, actor, server, default_serializer)
+        return await _actor_execution(message, actor, actor_context)
 
     interval = (
         actor.keep_alive
         if isinstance(actor.keep_alive, (int, float)) and not isinstance(actor.keep_alive, bool)
         else message.keep_alive_interval
     )
-    if not server.capabilities["supports_keep_alive"] or interval is None:
-        return await _actor_execution(message, actor, server, default_serializer)
+    if not actor_context.server.capabilities["supports_keep_alive"] or interval is None:
+        return await _actor_execution(message, actor, actor_context)
 
     keepalive_task = asyncio.create_task(_keep_alive_loop(message, interval))
     try:
-        return await _actor_execution(message, actor, server, default_serializer)
+        return await _actor_execution(message, actor, actor_context)
     finally:
         keepalive_task.cancel()
         with suppress(asyncio.CancelledError):
@@ -78,17 +75,16 @@ async def _run_with_keepalive(
 async def _actor_execution_with_confirmation(  # noqa: C901, PLR0912
     message: ReceivedMessageT,
     actor: ActorData,
-    server: ServerT,
-    default_serializer: SerializerT,
+    actor_context: ActorExecutionContext,
 ) -> ActorResultT:
     """Wraps `_actor_execution` to ack/nack the message immediately after the actor fn runs,
     so middlewares unwinding above this leaf can observe `message.action`."""
     try:
         if actor.timeout is None or actor.timeout <= 0 or actor.timeout == float("inf"):
-            result = await _run_with_keepalive(message, actor, server, default_serializer)
+            result = await _run_with_keepalive(message, actor, actor_context)
         else:
             result = await asyncio.wait_for(
-                _run_with_keepalive(message, actor, server, default_serializer),
+                _run_with_keepalive(message, actor, actor_context),
                 timeout=actor.timeout,
             )
     except Exception as exc:
@@ -131,8 +127,7 @@ async def _actor_execution_with_confirmation(  # noqa: C901, PLR0912
 async def _actor_run(
     actor: ActorData,
     message: ReceivedMessageT,
-    server: ServerT,
-    default_serializer: SerializerT,
+    actor_context: ActorExecutionContext,
 ) -> ActorResultT | Exception:
     if (
         not message.is_acted_on  # theoretically a server can automatically ack the message on receive
@@ -151,8 +146,7 @@ async def _actor_run(
 
     leaf = partial(
         _actor_execution_with_confirmation,
-        server=server,
-        default_serializer=default_serializer,
+        actor_context=actor_context,
     )
 
     try:
@@ -172,13 +166,12 @@ async def _actor_run(
 async def _actor_run_with_cancel_event_and_callback(
     actor: ActorData,
     message: ReceivedMessageT,
-    server: ServerT,
-    default_serializer: SerializerT,
+    actor_context: ActorExecutionContext,
     cancel_event: asyncio.Event,
     cancel_event_task: asyncio.Task,
     callback: Callable[[], Awaitable],
 ) -> None:
-    process_task = asyncio.create_task(_actor_run(actor, message, server, default_serializer))
+    process_task = asyncio.create_task(_actor_run(actor, message, actor_context))
     await asyncio.wait(
         {cancel_event_task, process_task},
         return_when=asyncio.FIRST_COMPLETED,
@@ -212,8 +205,8 @@ class _Runner:
         "_tasks",
         "_tasks_concurrency_limit",
         "_unrouted_seen_counts",
+        "actor_context",
         "cancel_event",
-        "default_serializer",
         "max_tasks",
         "max_unrouted_retries",
         "server",
@@ -223,15 +216,14 @@ class _Runner:
     def __init__(
         self,
         *,
-        server: ServerT,
+        actor_context: ActorExecutionContext,
         max_tasks: int = float("inf"),  # type: ignore[assignment]
         tasks_concurrency_limit: int = 1000,
         concurrency_unpause_percent: float = 0.1,  # 10 percent
         health_check_server: HealthCheckServer | None = None,
-        default_serializer: SerializerT,
         max_unrouted_retries: int = 10,
     ):
-        self.server = server
+        self.server = actor_context.server
         self._server_subscriber: SubscriberT | None = None
         self._server_subscriber_concurrency_unpause_threshold = max(
             math.ceil(tasks_concurrency_limit * concurrency_unpause_percent),
@@ -259,7 +251,7 @@ class _Runner:
 
         self._health_check_server = health_check_server
 
-        self.default_serializer = default_serializer
+        self.actor_context = actor_context
 
     @property
     def processed(self) -> int:
@@ -343,8 +335,7 @@ class _Runner:
             _actor_run_with_cancel_event_and_callback(
                 actor,
                 message,
-                self.server,
-                self.default_serializer,
+                self.actor_context,
                 self.cancel_event,
                 self.cancel_event_task,
                 self._actor_run_callback,

{repid-2.1.2 → repid-2.1.3}/repid/_worker.py

@@ -9,24 +9,22 @@ from typing import TYPE_CHECKING
 
 from repid._runner import _Runner
 from repid.asyncapi_server import AsyncAPIServer
+from repid.data.actor import ActorExecutionContext
 from repid.health_check_server import HealthCheckServer
 from repid.router import Router
-from repid.serializer import default_serializer as repid_default_serializer
 
 logger = logging.getLogger("repid")
 
 if TYPE_CHECKING:
     from repid.asyncapi import AsyncAPI3Schema
     from repid.asyncapi_server import AsyncAPIServerSettings
-    from repid.connections.abc import ServerT
     from repid.health_check_server import HealthCheckServerSettings
-    from repid.serializer import SerializerT
 
 
 class _Worker:
     def __init__(
         self,
-        server: ServerT,
+        actor_context: ActorExecutionContext,
         router: Router,
         graceful_shutdown_time: float = 25.0,
         messages_limit: int = float("inf"),  # type: ignore[assignment]
@@ -35,9 +33,9 @@ class _Worker:
         health_check_server: HealthCheckServerSettings | None = None,
         asyncapi_server: AsyncAPIServerSettings | None = None,
         asyncapi_schema: AsyncAPI3Schema | None = None,
-        default_serializer: SerializerT | None = None,
     ):
-        self.server: ServerT = server
+        self.actor_context = actor_context
+        self.server = actor_context.server
         self.centralized_router = router
 
         self.tasks_limit: int = tasks_limit
@@ -66,8 +64,6 @@ class _Worker:
                 raise ValueError("AsyncAPI schema is required if AsyncAPI server is enabled.")
             self.asyncapi_server = AsyncAPIServer(asyncapi_schema, asyncapi_server)
 
-        self.default_serializer = default_serializer or repid_default_serializer
-
     async def run(self) -> _Runner:
         logger.info(
             "worker.run.start",
@@ -85,11 +81,10 @@ class _Worker:
             await self.asyncapi_server.start()
 
         runner = _Runner(
-            server=self.server,
+            actor_context=self.actor_context,
             max_tasks=self.messages_limit,
             tasks_concurrency_limit=self.tasks_limit,
             health_check_server=self.health_check_server,
-            default_serializer=self.default_serializer,
         )
 
         if not self.centralized_router.actors:

{repid-2.1.2 → repid-2.1.3}/repid/connections/abc.py

@@ -4,7 +4,9 @@ import asyncio
 from collections.abc import Callable, Coroutine, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Protocol, TypedDict
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, TypedDict
+
+from repid.data.message import MessageData
 
 if TYPE_CHECKING:
     from repid.asyncapi.models.common import ServerBindingsObject
@@ -37,6 +39,12 @@ class SentMessageT(BaseMessageT, Protocol):
     pass
 
 
+MessagePublisherT: TypeAlias = Callable[
+    [str, MessageData, dict[str, Any] | None],
+    Coroutine[Any, Any, Any],
+]
+
+
 class ReceivedMessageT(BaseMessageT, Protocol):
     @property
     def channel(self) -> str: ...