austial-microservices 0.5.0__tar.gz

austial_microservices-0.5.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+.claude/settings.local.json
+coverage.xml

austial_microservices-0.5.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: austial-microservices
+Version: 0.5.0
+Summary: Message-driven applications: @MessagePattern / @EventPattern handlers served over TCP, in-process, Redis (Pub/Sub and Streams), NATS, Kafka, MQTT, RabbitMQ and gRPC (JSON or protobuf with streaming), plus ClientProxy and hybrid apps -- mirrors @nestjs/microservices.
+Requires-Python: >=3.11
+Requires-Dist: austial-core
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.66; extra == 'grpc'
+Provides-Extra: grpc-proto
+Requires-Dist: grpcio-tools>=1.66; extra == 'grpc-proto'
+Requires-Dist: grpcio>=1.66; extra == 'grpc-proto'
+Requires-Dist: protobuf>=5; extra == 'grpc-proto'
+Provides-Extra: kafka
+Requires-Dist: aiokafka>=0.11; extra == 'kafka'
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt>=2.3; extra == 'mqtt'
+Provides-Extra: nats
+Requires-Dist: nats-py>=2.9; extra == 'nats'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika>=9.4; extra == 'rabbitmq'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'

austial_microservices-0.5.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "austial-microservices"
+dynamic = ["version"]
+description = "Message-driven applications: @MessagePattern / @EventPattern handlers served over TCP, in-process, Redis (Pub/Sub and Streams), NATS, Kafka, MQTT, RabbitMQ and gRPC (JSON or protobuf with streaming), plus ClientProxy and hybrid apps -- mirrors @nestjs/microservices."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-core",
+]
+
+[project.optional-dependencies]
+# Each broker library is imported lazily and raises an install hint when missing.
+redis = ["redis>=5.0"]
+nats = ["nats-py>=2.9"]
+kafka = ["aiokafka>=0.11"]
+mqtt = ["aiomqtt>=2.3"]
+rabbitmq = ["aio-pika>=9.4"]
+grpc = ["grpcio>=1.66"]
+grpc-proto = ["grpcio>=1.66", "grpcio-tools>=1.66", "protobuf>=5"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-core = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_microservices-0.5.0/src/austial/microservices/__init__.py

@@ -0,0 +1,65 @@
+"""``austial.microservices`` -- message-driven services, mirrors ``@nestjs/microservices``.
+
+from austial.microservices import (
+    MessagePattern, EventPattern, Payload, Ctx, ClientsModule, ClientProxy, ClientOptions,
+    MicroserviceOptions, Transport, create_microservice,
+)
+"""
+
+from austial.microservices.client import ClientProxy, ClientsModule
+from austial.microservices.decorators import Ctx, EventPattern, MessagePattern, Payload
+from austial.microservices.factory import build_client_transport, build_server_transport
+from austial.microservices.microservice import (
+    MicroserviceApplication,
+    attach_microservice,
+    create_microservice,
+)
+from austial.microservices.server import HandlerRegistry, MicroserviceServer, RpcContext, RpcExecutionContext
+from austial.microservices.transport import (
+    ClientOptions,
+    ClientTransport,
+    LocalClient,
+    LocalServer,
+    MicroserviceOptions,
+    RpcError,
+    RpcException,
+    ServerTransport,
+    TcpClient,
+    TcpServer,
+    Transport,
+    pattern_key,
+)
+from austial.microservices.transports.grpc_proto import GrpcMethod
+from austial.microservices.transports.pubsub import JsonCodec
+
+__all__ = [
+    "ClientOptions",
+    "ClientProxy",
+    "ClientTransport",
+    "ClientsModule",
+    "Ctx",
+    "EventPattern",
+    "GrpcMethod",
+    "HandlerRegistry",
+    "JsonCodec",
+    "LocalClient",
+    "LocalServer",
+    "MessagePattern",
+    "MicroserviceApplication",
+    "MicroserviceOptions",
+    "MicroserviceServer",
+    "Payload",
+    "RpcContext",
+    "RpcError",
+    "RpcException",
+    "RpcExecutionContext",
+    "ServerTransport",
+    "TcpClient",
+    "TcpServer",
+    "Transport",
+    "attach_microservice",
+    "build_client_transport",
+    "build_server_transport",
+    "create_microservice",
+    "pattern_key",
+]

austial_microservices-0.5.0/src/austial/microservices/client.py

@@ -0,0 +1,71 @@
+"""``ClientProxy`` and ``ClientsModule`` -- mirror Nest's: talk to another microservice.
+
+::
+
+    @Module(imports=[ClientsModule.register([ClientOptions(name="MATH", port=3001)])])
+    class AppModule: ...
+
+    @Injectable()
+    class Calculator:
+        def __init__(self, math: ClientProxy = Inject("MATH")):
+            self.math = math
+
+        async def total(self, numbers):
+            return await self.math.send({"cmd": "sum"}, numbers)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any
+
+from austial.common.decorators.modules import Module
+from austial.core.dynamic_module import DynamicModule
+from austial.microservices.factory import build_client_transport
+from austial.microservices.transport import ClientOptions, ClientTransport, pattern_key
+
+
+class ClientProxy:
+    def __init__(self, options: ClientOptions, transport: ClientTransport | None = None):
+        self.options = options
+        self.transport = transport or build_client_transport(options)
+
+    async def connect(self) -> None:
+        await self.transport.connect()
+
+    async def send(self, pattern: Any, data: Any = None, *, timeout: float | None = None) -> Any:
+        """Request-response: returns the handler's result, raises ``RpcError`` if it failed or
+        ``asyncio.TimeoutError`` if nothing answered in ``timeout`` seconds (default: the client's)."""
+        wait = timeout if timeout is not None else self.options.timeout
+        return await asyncio.wait_for(self.transport.request(pattern_key(pattern), data), wait)
+
+    async def emit(self, pattern: Any, data: Any = None) -> None:
+        """Fire-and-forget event."""
+        await self.transport.emit(pattern_key(pattern), data)
+
+    def get_service(self, name: str) -> Any:
+        """Protobuf gRPC only: a ``.proto`` service client, e.g. ``get_service("HeroService").find_one({})``."""
+        getter = getattr(self.transport, "get_service", None)
+        if getter is None:
+            raise TypeError("get_service() needs Transport.GRPC with extra={'proto_path': ...}")
+        return getter(name)
+
+    async def close(self) -> None:
+        await self.transport.close()
+
+    # lifecycle: connect when the app initialises, close when it shuts down
+    async def on_module_init(self) -> None:
+        await self.connect()
+
+    async def on_module_destroy(self) -> None:
+        await self.close()
+
+
+@Module()
+class ClientsModule:
+    @staticmethod
+    def register(clients: Sequence[ClientOptions]) -> DynamicModule:
+        """Registers one :class:`ClientProxy` per entry, injectable as ``Inject(options.name)``."""
+        providers = [{"provide": c.name, "useValue": ClientProxy(c)} for c in clients]
+        return DynamicModule(module=ClientsModule, providers=providers, exports=[c.name for c in clients])

austial_microservices-0.5.0/src/austial/microservices/decorators.py

@@ -0,0 +1,55 @@
+"""``@MessagePattern``, ``@EventPattern``, ``@Payload`` and ``@Ctx`` -- mirror ``@nestjs/microservices``.
+
+::
+
+    @Controller()
+    class MathController:
+        @MessagePattern({"cmd": "sum"})                  # request-response: the return value is the reply
+        def accumulate(self, numbers: list[int] = Payload()) -> int:
+            return sum(numbers)
+
+        @EventPattern("user.created")                    # fire-and-forget: nothing is returned to the sender
+        async def on_user_created(self, user: dict = Payload()): ...
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.core.metadata import get_metadata, set_metadata
+
+MESSAGE_PATTERN_METADATA = "austial:rpc:message_pattern"
+EVENT_PATTERN_METADATA = "austial:rpc:event_pattern"
+
+
+def MessagePattern(pattern: Any) -> Callable:  # noqa: N802
+    return set_metadata(MESSAGE_PATTERN_METADATA, pattern)
+
+
+def EventPattern(pattern: Any) -> Callable:  # noqa: N802
+    def decorator(fn):
+        existing = list(get_metadata(EVENT_PATTERN_METADATA, fn, []))
+        set_metadata(EVENT_PATTERN_METADATA, [*existing, pattern])(fn)
+        return fn
+
+    return decorator
+
+
+class PayloadMarker:
+    def __init__(self, key: str | None):
+        self.key = key
+
+
+class CtxMarker:
+    pass
+
+
+def Payload(key: str | None = None) -> Any:  # noqa: N802
+    """The message data (or, with ``key``, one field of it)."""
+    return PayloadMarker(key)
+
+
+def Ctx() -> Any:  # noqa: N802
+    """An :class:`RpcContext` with the pattern that matched."""
+    return CtxMarker()

austial_microservices-0.5.0/src/austial/microservices/factory.py

@@ -0,0 +1,109 @@
+"""Turns ``MicroserviceOptions`` / ``ClientOptions`` into the right transport object."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.microservices.transport import (
+    ClientOptions,
+    ClientTransport,
+    LocalClient,
+    LocalServer,
+    MicroserviceOptions,
+    ServerTransport,
+    TcpClient,
+    TcpServer,
+    Transport,
+)
+
+
+def _split_host_port(url: str | None, default_host: str, default_port: int) -> tuple[str, int]:
+    if not url:
+        return default_host, default_port
+    host, _, port = url.removeprefix("mqtt://").rpartition(":")
+    return (host or url, int(port)) if port.isdigit() else (url, default_port)
+
+
+def _backend(transport: Transport, url: str | None, group: str, extra: dict[str, Any]) -> Any:
+    from austial.microservices.transports import (
+        KafkaBackend,
+        MqttBackend,
+        NatsBackend,
+        RabbitMqBackend,
+        RedisBackend,
+        RedisStreamsBackend,
+    )
+
+    if transport == Transport.REDIS:
+        return RedisBackend(url or "redis://localhost:6379", **extra)
+    if transport == Transport.REDIS_STREAMS:
+        return RedisStreamsBackend(url or "redis://localhost:6379", **extra)
+    if transport == Transport.NATS:
+        return NatsBackend(url or "nats://localhost:4222", **extra)
+    if transport == Transport.KAFKA:
+        return KafkaBackend(url or "localhost:9092", group=group, **extra)
+    if transport == Transport.MQTT:
+        host, port = _split_host_port(url, "localhost", 1883)
+        return MqttBackend(host, port, **extra)
+    if transport == Transport.RMQ:
+        return RabbitMqBackend(url or "amqp://guest:guest@localhost/", **extra)
+    raise ValueError(f"Not a broker transport: {transport}")
+
+
+_BROKERS = {Transport.REDIS, Transport.REDIS_STREAMS, Transport.NATS, Transport.KAFKA, Transport.MQTT, Transport.RMQ}
+
+
+def build_server_transport(options: MicroserviceOptions) -> ServerTransport:
+    if options.transport == Transport.TCP:
+        return TcpServer(options.host, options.port)
+    if options.transport == Transport.LOCAL:
+        return LocalServer(options.name)
+    if options.transport in _BROKERS:
+        from austial.microservices.transports import PubSubServer
+
+        # NATS, MQTT, Kafka and Redis Streams share load through the group; RabbitMQ shares by queue
+        grouped = options.transport in (Transport.NATS, Transport.MQTT, Transport.REDIS_STREAMS, Transport.KAFKA)
+        return PubSubServer(
+            _backend(options.transport, options.url, options.group, options.extra),
+            prefix=options.prefix,
+            group=options.group if grouped else None,
+            codec=options.codec,
+        )
+    if options.transport == Transport.GRPC:
+        if "proto_path" in options.extra:  # a .proto file: real protobuf services
+            from austial.microservices.transports.grpc_proto import GrpcProtoServer
+
+            return GrpcProtoServer(options.host, options.port, **options.extra)
+        from austial.microservices.transports import GrpcServer
+
+        return GrpcServer(options.host, options.port, **options.extra)
+    if options.custom_server is None:
+        raise ValueError("Transport.CUSTOM needs custom_server=")
+    return options.custom_server
+
+
+def build_client_transport(options: ClientOptions) -> ClientTransport:
+    if options.transport == Transport.TCP:
+        return TcpClient(options.host, options.port, options.timeout)
+    if options.transport == Transport.LOCAL:
+        return LocalClient(options.broker)
+    if options.transport in _BROKERS:
+        from austial.microservices.transports import PubSubClient
+
+        return PubSubClient(
+            _backend(options.transport, options.url, "austial", options.extra),
+            prefix=options.prefix,
+            timeout=options.timeout,
+            codec=options.codec,
+        )
+    if options.transport == Transport.GRPC:
+        if "proto_path" in options.extra:
+            from austial.microservices.transports.grpc_proto import GrpcProtoClient
+
+            return GrpcProtoClient(options.host, options.port, timeout=options.timeout, **options.extra)
+        from austial.microservices.transports import GrpcClient
+
+        return GrpcClient(options.host, options.port, timeout=options.timeout, **options.extra)
+    if options.custom_client is None:
+        raise ValueError(f"Client '{options.name}': Transport.CUSTOM needs custom_client=")
+    return options.custom_client

austial_microservices-0.5.0/src/austial/microservices/microservice.py

@@ -0,0 +1,52 @@
+"""Standalone and hybrid microservices."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.core.application_context import AustialApplicationContext
+from austial.core.container import Container
+from austial.core.discovery import DiscoveryService
+from austial.core.module_ref import ModuleRef
+from austial.core.module_scanner import scan_module
+from austial.microservices.factory import build_server_transport
+from austial.microservices.server import HandlerRegistry, MicroserviceServer
+from austial.microservices.transport import MicroserviceOptions
+
+
+def build_server(container: Container, options: MicroserviceOptions) -> MicroserviceServer:
+    registry = HandlerRegistry(container.resolve(DiscoveryService), container.resolve(ModuleRef))
+    return MicroserviceServer(build_server_transport(options), registry)
+
+
+class MicroserviceApplication(AustialApplicationContext):
+    """What ``create_microservice`` returns: a DI context plus a transport server.
+
+    ``await ms.listen()`` initialises the app (hooks, async providers) and starts the transport;
+    ``await ms.close()`` stops it and runs the shutdown hooks.
+    """
+
+    def __init__(self, container: Container, options: MicroserviceOptions):
+        super().__init__(container)
+        self.options = options
+        self.server = build_server(container, options)
+
+    async def listen(self) -> None:
+        await self.init()
+        await self.server.start()
+
+    async def close(self, signal: str | None = None) -> None:
+        await self.server.stop()
+        await super().close(signal)
+
+
+def create_microservice(root_module: type, options: MicroserviceOptions) -> MicroserviceApplication:
+    """Mirrors ``NestFactory.createMicroservice()``: a message-driven app with no HTTP server."""
+    container = Container()
+    scan_module(root_module, container)
+    return MicroserviceApplication(container, options)
+
+
+def attach_microservice(app: Any, options: MicroserviceOptions) -> MicroserviceServer:
+    """Hybrid app: serve ``options`` from the same application as HTTP. Used by ``app.connect_microservice()``."""
+    return build_server(app._container, options)  # noqa: SLF001

austial_microservices-0.5.0/src/austial/microservices/server.py

@@ -0,0 +1,172 @@
+"""Dispatches transport messages to ``@MessagePattern`` / ``@EventPattern`` handlers found on providers and
+controllers, through guards, pipes and interceptors."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any
+
+from austial.common.guards.base import ExecutionContext
+from austial.common.interceptors.base import CallHandler
+from austial.common.logger import Logger
+from austial.common.pipes.validation_pipe import ArgumentMetadata
+from austial.core.discovery import DiscoveryService
+from austial.core.metadata import GUARDS_METADATA, INTERCEPTORS_METADATA, PIPES_METADATA, get_metadata
+from austial.core.module_ref import ModuleRef
+from austial.microservices.decorators import (
+    EVENT_PATTERN_METADATA,
+    MESSAGE_PATTERN_METADATA,
+    CtxMarker,
+    PayloadMarker,
+)
+from austial.microservices.transport import RpcException, ServerTransport, pattern_key
+
+_logger = Logger("MicroserviceServer")
+
+
+@dataclass
+class RpcContext:
+    pattern: str
+    kind: str  # "request" | "event"
+
+
+class RpcExecutionContext(ExecutionContext):
+    """``get_type()`` is ``"rpc"``; ``switch_to_rpc()`` gives the data and the :class:`RpcContext`."""
+
+    def __init__(self, data: Any, rpc: RpcContext, controller_class: type, handler: Any):
+        super().__init__(None, controller_class, handler)  # type: ignore[arg-type]
+        self._data, self._rpc = data, rpc
+
+    def get_type(self) -> str:
+        return "rpc"
+
+    def switch_to_rpc(self) -> RpcExecutionContext:
+        return self
+
+    def get_data(self) -> Any:
+        return self._data
+
+    def get_context(self) -> RpcContext:
+        return self._rpc
+
+    def switch_to_http(self) -> ExecutionContext:
+        raise NotImplementedError("This is an RPC execution context: use switch_to_rpc().")
+
+
+async def _maybe(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class HandlerRegistry:
+    """All the handlers of one application, discovered from its providers and controllers."""
+
+    def __init__(self, discovery: DiscoveryService, module_ref: ModuleRef):
+        self.discovery, self.module_ref = discovery, module_ref
+        self._messages: dict[str, tuple[Any, Any]] = {}
+        self._events: dict[str, list[tuple[Any, Any]]] = {}
+        self._built = False
+
+    def build(self) -> None:
+        if self._built:
+            return
+        self._built = True
+        for controllers in (False, True):
+            for wrapper, name, pattern in self.discovery.get_methods_with_metadata(
+                MESSAGE_PATTERN_METADATA, controllers=controllers
+            ):
+                key = pattern_key(pattern)
+                if key in self._messages:
+                    raise RuntimeError(f"Two handlers for the message pattern {key}")
+                self._messages[key] = (wrapper.instance, getattr(wrapper.instance, name))
+            for wrapper, name, patterns in self.discovery.get_methods_with_metadata(
+                EVENT_PATTERN_METADATA, controllers=controllers
+            ):
+                for pattern in patterns:
+                    self._events.setdefault(pattern_key(pattern), []).append(
+                        (wrapper.instance, getattr(wrapper.instance, name))
+                    )
+
+    def patterns(self) -> dict[str, list[str]]:
+        """The pattern keys this application handles, for transports that must subscribe to topics up front."""
+        self.build()
+        return {"request": list(self._messages), "event": list(self._events)}
+
+    async def handle(self, kind: str, pattern: str, data: Any) -> Any:
+        self.build()
+        context = RpcContext(pattern, kind)
+        if kind == "event":
+            for owner, handler in self._events.get(pattern, []):
+                try:
+                    await self._run(owner, handler, data, context)
+                except Exception as exc:  # noqa: BLE001
+                    _logger.error(f"Event handler for {pattern} raised {type(exc).__name__}: {exc}")
+            return None
+        entry = self._messages.get(pattern)
+        if entry is None:
+            raise RpcException(f"There is no matching message handler for {pattern}")
+        owner, handler = entry
+        return await self._run(owner, handler, data, context)
+
+    def _components(self, key: str, owner: Any, handler: Any) -> list[Any]:
+        raw = [*get_metadata(key, type(owner), []), *get_metadata(key, handler, [])]
+        return [self.module_ref.get(c) if isinstance(c, type) else c for c in raw]
+
+    async def _run(self, owner: Any, handler: Any, data: Any, rpc: RpcContext) -> Any:
+        context = RpcExecutionContext(data, rpc, type(owner), handler)
+        for guard in self._components(GUARDS_METADATA, owner, handler):
+            if not await _maybe(guard.can_activate(context)):
+                raise RpcException("Forbidden resource")
+        pipes = self._components(PIPES_METADATA, owner, handler)
+        kwargs: dict[str, Any] = {}
+        data_used = False
+        for name, param in inspect.signature(handler, eval_str=True).parameters.items():
+            default = param.default
+            if isinstance(default, CtxMarker):
+                kwargs[name] = rpc
+                continue
+            if isinstance(default, PayloadMarker):
+                value = data.get(default.key) if default.key and isinstance(data, dict) else data
+            elif not data_used and default is inspect.Parameter.empty:
+                value = data
+            else:
+                continue
+            data_used = True
+            for pipe in pipes:
+                value = await _maybe(pipe.transform(value, ArgumentMetadata(type="body", data=name, metatype=None)))
+            kwargs[name] = value
+
+        async def call() -> Any:
+            return await _maybe(handler(**kwargs))
+
+        chain = call
+        for interceptor in reversed(self._components(INTERCEPTORS_METADATA, owner, handler)):
+            chain = _wrap(interceptor, context, chain)
+        return await chain()
+
+
+def _wrap(interceptor: Any, context: RpcExecutionContext, next_call: Any):
+    async def wrapped() -> Any:
+        return await interceptor.intercept(context, CallHandler(next_call))
+
+    return wrapped
+
+
+class MicroserviceServer:
+    """A transport plus the application's handlers. ``await start()`` / ``await stop()``."""
+
+    def __init__(self, transport: ServerTransport, registry: HandlerRegistry):
+        self.transport, self.registry = transport, registry
+        self.running = False
+
+    async def start(self) -> None:
+        if self.running:
+            return
+        self.transport.patterns = self.registry.patterns()
+        await self.transport.listen(self.registry.handle)
+        self.running = True
+
+    async def stop(self) -> None:
+        if self.running:
+            await self.transport.close()
+            self.running = False