server-decorator 2.0.0__py3-none-any.whl

server_decorator/__init__.py

@@ -0,0 +1,61 @@
+"""server-decorator (Python) — public API barrel.
+
+Mirrors `node/src/index.ts`. Method-form decorators behave identically to the Node
+versions on the same inputs (per `contracts/`). Class-form decorators (Decision #4)
+auto-wrap every qualifying method.
+"""
+
+from server_decorator._contract import CONTRACT_VERSION
+from server_decorator._version import __version__
+from server_decorator.decorators.cache import CACHE_MISS, cache, cache_class
+from server_decorator.decorators.emit_on_success import emit_on_success, emit_on_success_class
+from server_decorator.decorators.tracking import tracking, tracking_class
+from server_decorator.emitter import global_emitter
+from server_decorator.logger import Logger, global_logger, set_global_logger
+from server_decorator.queue.adapter import (
+    QueueAdapter,
+    global_queue,
+    has_global_queue,
+    set_global_queue,
+)
+from server_decorator.queue.adapters.inmemory import InMemoryQueueAdapter
+from server_decorator.queue.adapters.noop import NoOpQueueAdapter
+from server_decorator.queue.message import QueueMessage
+from server_decorator.queue.registry import QueueConfig, QueueRegistry, global_queue_registry
+from server_decorator.tracker import Tracker, global_tracker, set_global_tracker
+
+__all__ = [
+    "__version__",
+    "CONTRACT_VERSION",
+    # method-form decorators (mirror Node)
+    "cache",
+    "tracking",
+    "emit_on_success",
+    # class-form decorators (Decision #4)
+    "cache_class",
+    "tracking_class",
+    "emit_on_success_class",
+    # cache miss sentinel (D-B)
+    "CACHE_MISS",
+    # logger
+    "Logger",
+    "global_logger",
+    "set_global_logger",
+    # tracker
+    "Tracker",
+    "global_tracker",
+    "set_global_tracker",
+    # in-process emitter
+    "global_emitter",
+    # queue
+    "QueueMessage",
+    "QueueAdapter",
+    "global_queue",
+    "set_global_queue",
+    "has_global_queue",
+    "QueueRegistry",
+    "global_queue_registry",
+    "QueueConfig",
+    "InMemoryQueueAdapter",
+    "NoOpQueueAdapter",
+]

server_decorator/_contract.py

@@ -0,0 +1,3 @@
+"""Contract version this package targets. Mirrors contracts/VERSION."""
+
+CONTRACT_VERSION = "1.0.0"

server_decorator/_version.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

server_decorator/decorators/__init__.py

@@ -0,0 +1 @@
+"""Decorators subsystem."""

server_decorator/decorators/_cache_key.py

@@ -0,0 +1,35 @@
+"""Cache key algorithm. Spec: contracts/rules/cache-key.md (v1.0.0).
+
+Both Python and Node implement this from the same spec; Node's port lives at
+`node/src/decorators/_cache_key.ts`. Parity tests load
+`contracts/fixtures/cache-key.examples.json`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+MAX_KEY_BYTES = 250
+
+
+def _repr_arg(x: Any) -> str:
+    return json.dumps(x, sort_keys=True, default=str, separators=(",", ":"))
+
+
+def build_cache_key(
+    qualname: str,
+    args: tuple[Any, ...] | list[Any],
+    kwargs: dict[str, Any],
+) -> str:
+    arg_pieces = [_repr_arg(a) for a in args]
+    if kwargs:
+        for k in sorted(kwargs.keys()):
+            arg_pieces.append(f"{k}={_repr_arg(kwargs[k])}")
+    arg_repr = ",".join(arg_pieces)
+    raw = f"{qualname}({arg_repr})"
+    if len(raw.encode("utf-8")) <= MAX_KEY_BYTES:
+        return raw
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return f"{qualname}(sha256:{digest})"

server_decorator/decorators/_class_apply.py

@@ -0,0 +1,67 @@
+"""Class-decorator helper: walk vars(cls), apply a method-decorator to each qualifying member.
+
+Decision #4. The marker `__server_decorator_wrapped_by__` prevents double-wrapping when
+both class-level and method-level decoration apply (method-level wins).
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+_MARKER = "__server_decorator_wrapped_by__"
+
+
+def _is_wrapped_by(fn: Callable[..., Any], name: str) -> bool:
+    return name in getattr(fn, _MARKER, ())
+
+
+def _mark_wrapped(wrapper: Callable[..., Any], name: str) -> None:
+    existing: tuple[str, ...] = getattr(wrapper, _MARKER, ())
+    object.__setattr__(wrapper, _MARKER, (*existing, name))
+
+
+def apply_to_class(
+    cls: type,
+    method_decorator: Callable[[Callable[..., Any]], Callable[..., Any]],
+    *,
+    decorator_name: str,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+    wrap_properties: bool = False,
+) -> type:
+    for attr_name, attr in list(vars(cls).items()):
+        if attr_name in exclude:
+            continue
+        if attr_name.startswith("_") and attr_name not in include and not include_private:
+            continue
+
+        if isinstance(attr, classmethod):
+            inner = attr.__func__
+            if _is_wrapped_by(inner, decorator_name):
+                continue
+            wrapped = method_decorator(inner)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, classmethod(wrapped))
+        elif isinstance(attr, staticmethod):
+            inner = attr.__func__
+            if _is_wrapped_by(inner, decorator_name):
+                continue
+            wrapped = method_decorator(inner)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, staticmethod(wrapped))
+        elif isinstance(attr, property):
+            if not wrap_properties:
+                continue
+            # v1.1+: wrap fget/fset; deferred per N1.
+            continue
+        elif inspect.isfunction(attr) or inspect.iscoroutinefunction(attr):
+            if _is_wrapped_by(attr, decorator_name):
+                continue
+            wrapped = method_decorator(attr)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, wrapped)
+        # else: nested classes, plain attrs — ignored.
+    return cls

server_decorator/decorators/_qualname.py

@@ -0,0 +1,11 @@
+"""Qualname normaliser. Drops `<locals>` markers and keeps the last two segments
+so test-defined classes / nested classes match Node's `ClassName.methodName`."""
+
+from __future__ import annotations
+
+
+def shorten_qualname(qualname: str) -> str:
+    parts = [p for p in qualname.split(".") if p != "<locals>"]
+    if len(parts) >= 2:
+        return ".".join(parts[-2:])
+    return qualname

server_decorator/decorators/cache.py

@@ -0,0 +1,92 @@
+"""@cache decorator (method form) + cache_class (class form). Decisions #6 + D-B.
+
+The `CACHE_MISS` sentinel (D-B) lets users cache None/0/""/False as legitimate values:
+adapters return CACHE_MISS for absent keys; the decorator uses identity comparison
+(`cached is not CACHE_MISS`) to distinguish hit from miss.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, TypeVar, cast
+
+from server_decorator.decorators._cache_key import build_cache_key
+from server_decorator.decorators._class_apply import _mark_wrapped, apply_to_class
+from server_decorator.decorators._qualname import shorten_qualname
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# D-B: distinct sentinel so adapters can signal "absent key" without colliding with
+# legitimately-cached None/0/""/False values. Re-exported from the package barrel.
+CACHE_MISS: Any = object()
+
+
+class CacheAdapter(Protocol):
+    def get(self, key: str) -> Any | Awaitable[Any]: ...
+    def set(self, key: str, value: Any, ttl: int) -> Any | Awaitable[Any]: ...
+
+
+def cache(adapter: CacheAdapter, ttl: int) -> Callable[[F], F]:
+    def decorator(fn: F) -> F:
+        qualname = shorten_qualname(fn.__qualname__)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                key = build_cache_key(qualname, args, kwargs)
+                cached = adapter.get(key)
+                if inspect.isawaitable(cached):
+                    cached = await cached
+                if cached is not CACHE_MISS:
+                    return cached
+                result = await fn(*args, **kwargs)
+                set_result = adapter.set(key, result, ttl)
+                if inspect.isawaitable(set_result):
+                    await set_result
+                return result
+
+            _mark_wrapped(async_wrapper, "cache")
+            return cast(F, async_wrapper)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            key = build_cache_key(qualname, args, kwargs)
+            cached = adapter.get(key)
+            if cached is not CACHE_MISS:
+                return cached
+            result = fn(*args, **kwargs)
+            adapter.set(key, result, ttl)
+            return result
+
+        _mark_wrapped(sync_wrapper, "cache")
+        return cast(F, sync_wrapper)
+
+    return decorator
+
+
+def cache_class(
+    adapter: CacheAdapter,
+    ttl: int,
+    *,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+) -> Callable[[type], type]:
+    """Class form: auto-apply @cache to every public method. Decision #4."""
+
+    method_dec = cache(adapter, ttl)
+
+    def wrap(cls: type) -> type:
+        return apply_to_class(
+            cls,
+            method_dec,
+            decorator_name="cache",
+            include=include,
+            exclude=exclude,
+            include_private=include_private,
+        )
+
+    return wrap

server_decorator/decorators/emit_on_success.py

@@ -0,0 +1,171 @@
+"""@emit_on_success decorator (method form) + emit_on_success_class. Decisions #7 + D-C.
+
+When `use_queue=True` is set on a sync method called outside an event loop, the side
+effect runs on a single-worker `_EMIT_EXECUTOR` so the caller doesn't block (D-C).
+Register `atexit(_EMIT_EXECUTOR.shutdown, wait=True)` for delivery on shutdown.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import functools
+import inspect
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, TypeVar, cast
+
+from server_decorator import emitter as _emitter_mod
+from server_decorator import logger as _logger_mod
+from server_decorator.decorators._class_apply import _mark_wrapped, apply_to_class
+from server_decorator.decorators._qualname import shorten_qualname
+from server_decorator.queue import registry as _registry_mod
+from server_decorator.queue.message import QueueMessage
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# D-C: single-worker executor for sync-method fire-and-forget. I/O-bound and
+# ordering matters, so one worker is fine. Drained on shutdown via atexit.
+_EMIT_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
+    max_workers=1, thread_name_prefix="server-decorator-emit"
+)
+
+# Strong references to in-flight create_task() futures so the GC doesn't drop them
+# mid-flight (RUF006). Tasks self-remove via add_done_callback.
+_BACKGROUND_TASKS: set[asyncio.Task[None]] = set()
+
+
+@dataclass
+class EmitOnSuccessOptions:
+    transform: Callable[[Any], Any] | None = None
+    use_events: bool = True
+    use_queue: bool = False
+    queue: str | None = None
+    topic: str | None = None
+    queue_metadata: dict[str, Any] = field(default_factory=dict)
+    event_name: str | None = None
+
+
+def emit_on_success(
+    *,
+    transform: Callable[[Any], Any] | None = None,
+    use_events: bool = True,
+    use_queue: bool = False,
+    queue: str | None = None,
+    topic: str | None = None,
+    queue_metadata: dict[str, Any] | None = None,
+    event_name: str | None = None,
+) -> Callable[[F], F]:
+    opts = EmitOnSuccessOptions(
+        transform=transform,
+        use_events=use_events,
+        use_queue=use_queue,
+        queue=queue,
+        topic=topic,
+        queue_metadata=queue_metadata or {},
+        event_name=event_name,
+    )
+
+    def decorator(fn: F) -> F:
+        qualname = shorten_qualname(fn.__qualname__)
+        class_name, _, method_name = qualname.rpartition(".")
+        resolved_event = opts.event_name or qualname
+
+        async def _on_success(result: Any) -> None:
+            payload = opts.transform(result) if opts.transform else result
+            if opts.use_events:
+                try:
+                    _emitter_mod.global_emitter.emit(resolved_event, payload)
+                except Exception as e:
+                    _logger_mod.global_logger.error(f"Failed to emit event {resolved_event}: {e!r}")
+            if opts.use_queue:
+                try:
+                    msg: QueueMessage = {
+                        "eventName": resolved_event,
+                        "payload": payload,
+                        "timestamp": int(time.time() * 1000),
+                        "metadata": {
+                            "className": class_name,
+                            "methodName": method_name,
+                            "topic": opts.topic,
+                            **opts.queue_metadata,  # type: ignore[typeddict-item]
+                        },
+                    }
+                    if opts.queue or opts.topic:
+                        auto_topic = opts.topic or qualname
+                        await _registry_mod.global_queue_registry.publish(
+                            msg, opts.queue, auto_topic
+                        )
+                    else:
+                        await _registry_mod.global_queue_registry.publish(msg)
+                except Exception as e:
+                    _logger_mod.global_logger.error(f"Failed to publish to queue: {e!r}")
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                result = await fn(*args, **kwargs)
+                await _on_success(result)
+                return result
+
+            _mark_wrapped(async_wrapper, "emit_on_success")
+            return cast(F, async_wrapper)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            result = fn(*args, **kwargs)
+            try:
+                loop = asyncio.get_running_loop()
+                # Tracked in _BACKGROUND_TASKS to keep a strong reference (RUF006).
+                task = loop.create_task(_on_success(result))
+                _BACKGROUND_TASKS.add(task)
+                task.add_done_callback(_BACKGROUND_TASKS.discard)
+            except RuntimeError:
+                # D-C: no running loop — submit to executor so caller doesn't block.
+                _EMIT_EXECUTOR.submit(asyncio.run, _on_success(result))
+            return result
+
+        _mark_wrapped(sync_wrapper, "emit_on_success")
+        return cast(F, sync_wrapper)
+
+    return decorator
+
+
+def emit_on_success_class(
+    *,
+    transform: Callable[[Any], Any] | None = None,
+    use_events: bool = True,
+    use_queue: bool = False,
+    queue: str | None = None,
+    topic: str | None = None,
+    queue_metadata: dict[str, Any] | None = None,
+    event_name: str | None = None,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+) -> Callable[[type], type]:
+    """Class form: auto-apply @emit_on_success to every public method. Decision #4."""
+
+    method_dec = emit_on_success(
+        transform=transform,
+        use_events=use_events,
+        use_queue=use_queue,
+        queue=queue,
+        topic=topic,
+        queue_metadata=queue_metadata,
+        event_name=event_name,
+    )
+
+    def wrap(cls: type) -> type:
+        return apply_to_class(
+            cls,
+            method_dec,
+            decorator_name="emit_on_success",
+            include=include,
+            exclude=exclude,
+            include_private=include_private,
+        )
+
+    return wrap

server_decorator/decorators/tracking.py

@@ -0,0 +1,78 @@
+"""@tracking decorator (method form) + tracking_class (class form). Decision #5."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from server_decorator import logger as _logger_mod
+from server_decorator import tracker as _tracker_mod
+from server_decorator.decorators._class_apply import _mark_wrapped, apply_to_class
+from server_decorator.decorators._qualname import shorten_qualname
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def tracking(fn: F) -> F:
+    """Track latency and error rate. Mirrors Node `@tracking`. Re-raises any exception."""
+    qualname = shorten_qualname(fn.__qualname__)
+
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.monotonic()
+            is_error = False
+            try:
+                return await fn(*args, **kwargs)
+            except Exception as e:
+                is_error = True
+                _logger_mod.global_logger.error(f"[Tracking] {qualname} - Error: {e!r}")
+                raise
+            finally:
+                latency_ms = int((time.monotonic() - start) * 1000)
+                _tracker_mod.global_tracker.track(qualname, latency_ms, is_error)
+
+        _mark_wrapped(async_wrapper, "tracking")
+        return cast(F, async_wrapper)
+
+    @functools.wraps(fn)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        is_error = False
+        try:
+            return fn(*args, **kwargs)
+        except Exception as e:
+            is_error = True
+            _logger_mod.global_logger.error(f"[Tracking] {qualname} - Error: {e!r}")
+            raise
+        finally:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            _tracker_mod.global_tracker.track(qualname, latency_ms, is_error)
+
+    _mark_wrapped(sync_wrapper, "tracking")
+    return cast(F, sync_wrapper)
+
+
+def tracking_class(
+    *,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+) -> Callable[[type], type]:
+    """Class form: auto-apply @tracking to every public method. Decision #4."""
+
+    def wrap(cls: type) -> type:
+        return apply_to_class(
+            cls,
+            tracking,
+            decorator_name="tracking",
+            include=include,
+            exclude=exclude,
+            include_private=include_private,
+        )
+
+    return wrap

server_decorator/emitter.py

@@ -0,0 +1,30 @@
+"""In-process event emitter. Mirrors Node's `globalEmitter` (eventemitter3)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+_Listener = Callable[..., Any]
+
+
+class _Emitter:
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[_Listener]] = {}
+
+    def on(self, event: str, listener: _Listener) -> None:
+        self._listeners.setdefault(event, []).append(listener)
+
+    def off(self, event: str, listener: _Listener) -> None:
+        if event in self._listeners:
+            try:
+                self._listeners[event].remove(listener)
+            except ValueError:
+                pass
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> None:
+        for listener in list(self._listeners.get(event, [])):
+            listener(*args, **kwargs)
+
+
+global_emitter: _Emitter = _Emitter()

server_decorator/logger.py

@@ -0,0 +1,38 @@
+"""Pluggable logger. Default goes to the stdlib logger; override via `set_global_logger`."""
+
+from __future__ import annotations
+
+import logging
+from typing import Protocol
+
+
+class Logger(Protocol):
+    def debug(self, msg: object) -> None: ...
+    def info(self, msg: object) -> None: ...
+    def warn(self, msg: object) -> None: ...
+    def error(self, msg: object) -> None: ...
+
+
+class _DefaultLogger:
+    def __init__(self) -> None:
+        self._log = logging.getLogger("server_decorator")
+
+    def debug(self, msg: object) -> None:
+        self._log.debug("%s", msg)
+
+    def info(self, msg: object) -> None:
+        self._log.info("%s", msg)
+
+    def warn(self, msg: object) -> None:
+        self._log.warning("%s", msg)
+
+    def error(self, msg: object) -> None:
+        self._log.error("%s", msg)
+
+
+global_logger: Logger = _DefaultLogger()
+
+
+def set_global_logger(logger: Logger) -> None:
+    global global_logger
+    global_logger = logger

server_decorator/queue/__init__.py

@@ -0,0 +1 @@
+"""Queue subsystem: message format, adapter protocol, registry, built-in adapters."""

server_decorator/queue/adapter.py

@@ -0,0 +1,31 @@
+"""QueueAdapter Protocol + the global single-queue helpers (mirror Node's `globalQueue`)."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from server_decorator.queue.message import QueueMessage
+
+
+class QueueAdapter(Protocol):
+    async def publish(self, message: QueueMessage) -> None: ...
+
+
+global_queue: QueueAdapter | None = None
+
+
+def set_global_queue(adapter: QueueAdapter) -> None:
+    global global_queue
+    global_queue = adapter
+
+
+def has_global_queue() -> bool:
+    return global_queue is not None
+
+
+__all__ = ["QueueAdapter", "global_queue", "set_global_queue", "has_global_queue"]
+
+
+# Awaitable is imported only to keep the type stub importable in editor tooling
+_ = Awaitable

server_decorator/queue/adapters/__init__.py

@@ -0,0 +1 @@
+"""Built-in queue adapters."""

server_decorator/queue/adapters/inmemory.py

@@ -0,0 +1,20 @@
+"""In-memory queue adapter for unit tests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from server_decorator.queue.message import QueueMessage
+
+
+class InMemoryQueueAdapter:
+    def __init__(self) -> None:
+        self.messages: dict[str, list[QueueMessage]] = {}
+
+    async def publish(self, message: QueueMessage) -> None:
+        topic_raw: Any = (message.get("metadata") or {}).get("topic")
+        topic = topic_raw if isinstance(topic_raw, str) and topic_raw else "default"
+        self.messages.setdefault(topic, []).append(message)
+
+    def clear(self) -> None:
+        self.messages.clear()

server_decorator/queue/adapters/kafka_adapter.py

@@ -0,0 +1,26 @@
+"""Kafka adapter (aiokafka). Topic comes from the message metadata.
+
+The producer is typed `Any` to avoid pulling aiokafka's untyped surface into
+the strict-mypy boundary. The runtime expectation is `aiokafka.AIOKafkaProducer`
+or any duck-typed equivalent with `send_and_wait(topic, value, key=...)`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from server_decorator.queue.message import QueueMessage
+
+
+class KafkaAdapter:
+    def __init__(self, producer: Any, default_topic: str = "default") -> None:
+        self._producer = producer
+        self._default_topic = default_topic
+
+    async def publish(self, message: QueueMessage) -> None:
+        body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+        topic_raw = (message.get("metadata") or {}).get("topic")
+        topic = topic_raw if isinstance(topic_raw, str) and topic_raw else self._default_topic
+        key = message["eventName"].encode("utf-8")
+        await self._producer.send_and_wait(topic, body, key=key)

server_decorator/queue/adapters/noop.py

@@ -0,0 +1,10 @@
+"""No-op queue adapter — drops every message. Useful as a safe default."""
+
+from __future__ import annotations
+
+from server_decorator.queue.message import QueueMessage
+
+
+class NoOpQueueAdapter:
+    async def publish(self, message: QueueMessage) -> None:
+        return None

server_decorator/queue/adapters/rabbitmq_adapter.py

@@ -0,0 +1,38 @@
+"""RabbitMQ adapter (aio-pika).
+
+The channel is typed `Any` to avoid pulling aio-pika's untyped surface into the
+strict-mypy boundary. Runtime expectation: `aio_pika.abc.AbstractChannel`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from server_decorator.queue.message import QueueMessage
+
+
+class RabbitMQAdapter:
+    def __init__(
+        self,
+        channel: Any,
+        queue_or_exchange: str,
+        *,
+        exchange: bool = False,
+    ) -> None:
+        self._channel = channel
+        self._target = queue_or_exchange
+        self._is_exchange = exchange
+
+    async def publish(self, message: QueueMessage) -> None:
+        from aio_pika import Message
+
+        body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+        amqp_message = Message(body=body, content_type="application/json")
+        if self._is_exchange:
+            exchange = await self._channel.get_exchange(self._target)
+            topic_raw = (message.get("metadata") or {}).get("topic")
+            routing_key = topic_raw if isinstance(topic_raw, str) else "default"
+            await exchange.publish(amqp_message, routing_key=routing_key)
+        else:
+            await self._channel.default_exchange.publish(amqp_message, routing_key=self._target)

server_decorator/queue/adapters/redis_adapter.py

@@ -0,0 +1,22 @@
+"""Redis Streams adapter (XADD).
+
+The client is typed `Any` to avoid pulling redis-py's untyped surface into the
+strict-mypy boundary. Runtime expectation: `redis.asyncio.Redis` or equivalent.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from server_decorator.queue.message import QueueMessage
+
+
+class RedisStreamAdapter:
+    def __init__(self, client: Any, stream: str = "default") -> None:
+        self._client = client
+        self._stream = stream
+
+    async def publish(self, message: QueueMessage) -> None:
+        body = json.dumps(message, separators=(",", ":"))
+        await self._client.xadd(self._stream, {"data": body})

server_decorator/queue/message.py

@@ -0,0 +1,21 @@
+"""QueueMessage TypedDict — the wire format. See contracts/schemas/queue-message.schema.json."""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class QueueMessageMetadata(TypedDict, total=False):
+    className: str
+    methodName: str
+    topic: str | None
+
+
+class _QueueMessageRequired(TypedDict):
+    eventName: str
+    payload: Any
+    timestamp: int
+
+
+class QueueMessage(_QueueMessageRequired, total=False):
+    metadata: QueueMessageMetadata

server_decorator/queue/registry.py

@@ -0,0 +1,64 @@
+"""QueueRegistry — register multiple named adapters; route by name + topic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from server_decorator.queue.adapter import QueueAdapter
+from server_decorator.queue.message import QueueMessage
+
+
+@dataclass
+class QueueConfig:
+    adapter: QueueAdapter
+    default_topic: str = "default"
+    priority: int = 0
+
+
+class QueueRegistry:
+    def __init__(self) -> None:
+        self._configs: dict[str, QueueConfig] = {}
+        self._default_name: str | None = None
+
+    def register(self, name: str, config: QueueConfig | QueueAdapter) -> None:
+        if isinstance(config, QueueConfig):
+            self._configs[name] = config
+        else:
+            self._configs[name] = QueueConfig(adapter=config)
+        if self._default_name is None:
+            self._default_name = name
+
+    def set_default(self, name: str) -> None:
+        if name not in self._configs:
+            raise KeyError(f"queue {name!r} not registered")
+        self._default_name = name
+
+    def get(self, name: str | None = None) -> QueueConfig:
+        if name is not None:
+            if name not in self._configs:
+                raise KeyError(f"queue {name!r} not registered")
+            return self._configs[name]
+        if self._default_name is not None:
+            return self._configs[self._default_name]
+        if not self._configs:
+            raise RuntimeError("no queues registered")
+        return next(iter(self._configs.values()))
+
+    def clear(self) -> None:
+        self._configs.clear()
+        self._default_name = None
+
+    async def publish(
+        self,
+        message: QueueMessage,
+        queue_name: str | None = None,
+        topic: str | None = None,
+    ) -> None:
+        config = self.get(queue_name)
+        meta = dict(message.get("metadata") or {})
+        meta["topic"] = topic or meta.get("topic") or config.default_topic
+        message["metadata"] = meta  # type: ignore[typeddict-item]
+        await config.adapter.publish(message)
+
+
+global_queue_registry: QueueRegistry = QueueRegistry()

server_decorator/tracker.py

@@ -0,0 +1,26 @@
+"""Pluggable tracker. Default prints to logger; override via `set_global_tracker`."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from server_decorator import logger as _logger_mod
+
+
+class Tracker(Protocol):
+    def track(self, key: str, latency_ms: int, is_error: bool) -> None: ...
+
+
+class _DefaultTracker:
+    def track(self, key: str, latency_ms: int, is_error: bool) -> None:
+        _logger_mod.global_logger.info(
+            f"[Tracking] key={key} latency_ms={latency_ms} is_error={is_error}"
+        )
+
+
+global_tracker: Tracker = _DefaultTracker()
+
+
+def set_global_tracker(tracker: Tracker) -> None:
+    global global_tracker
+    global_tracker = tracker

server_decorator-2.0.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: server-decorator
+Version: 2.0.0
+Summary: Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package.
+Project-URL: Homepage, https://github.com/your-username/server-decorator
+Project-URL: Repository, https://github.com/your-username/server-decorator
+Project-URL: Issues, https://github.com/your-username/server-decorator/issues
+Author: server-decorator contributors
+License: MIT
+Keywords: caching,decorators,kafka,queue,rabbitmq,redis,tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: aio-pika>=9.4; extra == 'all'
+Requires-Dist: aiokafka>=0.11; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: aio-pika>=9.4; extra == 'dev'
+Requires-Dist: aiokafka>=0.11; extra == 'dev'
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: testcontainers[kafka,rabbitmq,redis]>=4.7; extra == 'dev'
+Provides-Extra: kafka
+Requires-Dist: aiokafka>=0.11; extra == 'kafka'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika>=9.4; extra == 'rabbitmq'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# server-decorator (Python)
+
+Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package — both share the wire-format contracts in [`../contracts`](../contracts).
+
+## Install
+
+```bash
+pip install server-decorator               # core
+pip install server-decorator[redis]        # + redis adapter
+pip install server-decorator[rabbitmq]     # + aio-pika adapter
+pip install server-decorator[kafka]        # + aiokafka adapter
+pip install server-decorator[all]          # all adapters
+```
+
+Requires Python 3.10+. `asyncio` only — no `trio`/`anyio` (Decision #10).
+
+## Quick start
+
+### Method form
+
+```python
+from server_decorator import tracking, cache, emit_on_success, CACHE_MISS
+
+class InMemoryCache:
+    def __init__(self): self._d = {}
+    def get(self, key): return self._d.get(key, CACHE_MISS)
+    def set(self, key, val, ttl): self._d[key] = val
+
+class OrderService:
+    @tracking
+    @cache(InMemoryCache(), ttl=300)
+    @emit_on_success(use_events=True)
+    async def create_order(self, customer_id: str, total: float) -> dict:
+        return {"customer_id": customer_id, "total": total, "status": "pending"}
+```
+
+### Class form (auto-wrap every public method)
+
+```python
+from server_decorator import tracking_class
+
+@tracking_class()
+class OrderService:
+    async def create_order(self, ...): ...    # auto-wrapped
+    async def cancel_order(self, ...): ...    # auto-wrapped
+    def _internal(self): ...                  # SKIPPED (leading underscore)
+```
+
+`tracking_class`, `cache_class`, and `emit_on_success_class` accept `include`, `exclude`, and `include_private` to override the default predicates.
+
+## Sync vs async
+
+Method-level decorators auto-detect coroutines via `inspect.iscoroutinefunction` and wrap accordingly (Decision #5). For `@emit_on_success(use_queue=True)` on a sync method called outside an event loop, the side effect runs on a single-worker `ThreadPoolExecutor` so the caller doesn't block (D-C). To drain in-flight emits at process exit:
+
+```python
+import atexit
+from server_decorator.decorators.emit_on_success import _EMIT_EXECUTOR
+atexit.register(_EMIT_EXECUTOR.shutdown, wait=True)
+```
+
+## Caching `None` / falsy values
+
+`CacheAdapter.get` returns `CACHE_MISS` (a module-level sentinel) when a key is absent — `None`/`0`/`""`/`False` are valid cached values. See [`../contracts/rules/cache-adapter.md`](../contracts/rules/cache-adapter.md).
+
+## License
+
+MIT.

server_decorator-2.0.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+server_decorator/__init__.py,sha256=GbYU-BVKtk3YlFiXCaUv3WmJxWt6izN4NoA7XhHGm3c,1992
+server_decorator/_contract.py,sha256=829g2iarn9_32W0TdNVuTXThQJDd-1Bd_LApE4NVY8A,100
+server_decorator/_version.py,sha256=_7OlQdbVkK4jad0CLdpI0grT-zEAb-qgFmH5mFzDXiA,22
+server_decorator/emitter.py,sha256=nO82oxxqjvcCTu4sgHaLt1QhSjBksoucEkvwza69SWg,870
+server_decorator/logger.py,sha256=1OzywwqjL_wUhvIX2oqtb-qMrECDyHEYKU7E9E-JSwA,950
+server_decorator/tracker.py,sha256=1wwbRG7cdjl0PMLTTD4Rm3U_AbUnklebOzPUuLy881o,686
+server_decorator/decorators/__init__.py,sha256=ZF0ClwuKfevMobKHj1HXZjyfwage58tvnAO4_SHE5bA,28
+server_decorator/decorators/_cache_key.py,sha256=37EBkhGo0btqyCyvUUraAF-NfVwWPGF5UFPK8RKei9s,994
+server_decorator/decorators/_class_apply.py,sha256=1TISfLzwBa2JMFYen2boqrjwGVVm7hc6nGj0cUgtkD8,2398
+server_decorator/decorators/_qualname.py,sha256=ilaPqNb03hdOly12iMK3CpsCJdBwUzqo5_QUmnpgULQ,388
+server_decorator/decorators/cache.py,sha256=r-Xd16YVkarZ30nBrzjcXln3Z-DVs3y_7dYd0EhaVSY,3060
+server_decorator/decorators/emit_on_success.py,sha256=95CgcN5Er2_ZOPAy33qHvTgq4oS6yMF2pZNUb4vajDU,6201
+server_decorator/decorators/tracking.py,sha256=jjYrgzWCy2nq7RISG06DeHq_0w1-BqKB32ryoYTjuXc,2521
+server_decorator/queue/__init__.py,sha256=eCQg3CrGoJ5QP7hwDNvKSuKXfrbtRKrmWSl86M_gnT0,86
+server_decorator/queue/adapter.py,sha256=NXVQzCihgPuHktuGk5oDxzWTsn4Q1_U-CwmYBSfYC7g,749
+server_decorator/queue/message.py,sha256=S_qXEkvajYXvQZTtllK7At3TZ0V_30jmga1HR5-bYFE,475
+server_decorator/queue/registry.py,sha256=dTGXnxw1DTmLuGZagMtxKj_4giz3tUpm2Cj76YBwQoE,2081
+server_decorator/queue/adapters/__init__.py,sha256=cIk1fRtd9MqIBZ7XFtgEappfdzwUHbV9TTlNWFAJ4G0,31
+server_decorator/queue/adapters/inmemory.py,sha256=H6IcEfIfftyBK9dJbgqzEeVG0ZFn7csNXNvYd00U8B4,619
+server_decorator/queue/adapters/kafka_adapter.py,sha256=cMsdlyaz9N-H_g-yRRcsoozhMm7K05ZA0BAIqdlLvCM,1024
+server_decorator/queue/adapters/noop.py,sha256=fhK0BNnvoB401V0p5WMPlOfXdbQSVIY5M5WJkPzkgq0,276
+server_decorator/queue/adapters/rabbitmq_adapter.py,sha256=X71PlZ2qIXC2wt6aVAbgp2PmZiQzqeXkzOOCd1eCj7I,1283
+server_decorator/queue/adapters/redis_adapter.py,sha256=ZEDgmBsT9Gz_d82pVxAefvt7lh7WL24iYP_Oo8akdhE,665
+server_decorator-2.0.0.dist-info/METADATA,sha256=Xvjtr-yo3IVH01QR2-P06_oGWs5zZKYgC2CytkQT2PI,4351
+server_decorator-2.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+server_decorator-2.0.0.dist-info/RECORD,,

server_decorator-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any