hexastack-grpc 0.0.0__py3-none-any.whl

hexastack_grpc/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_grpc import adapters, domain, infra
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+]

hexastack_grpc/adapters/server.py

@@ -0,0 +1,46 @@
+from collections.abc import Sequence
+
+import grpc
+
+from hexastack_grpc.infra.config import HexastackGrpcConfig
+
+__all__ = [
+    "create_async_grpc_server",
+    "run_grpc_server",
+]
+
+
+def create_async_grpc_server(
+    config: HexastackGrpcConfig,
+    interceptors: Sequence[grpc.aio.ServerInterceptor] | None = None,
+) -> grpc.aio.Server:
+    """Create an asynchronous grpc.aio.Server instance.
+
+    Args:
+        config: HexastackGrpcConfig options.
+        interceptors: Optional async server interceptors.
+
+    Returns:
+        Configured grpc.aio.Server instance.
+    """
+    server = grpc.aio.server(interceptors=interceptors or ())
+    server.add_insecure_port(f"{config.host}:{config.port}")
+    return server
+
+
+def run_grpc_server(
+    server: grpc.Server,
+    block: bool = True,
+) -> None:
+    """Start the gRPC server and optionally block the current thread.
+
+    Args:
+        server: Configured grpc.Server instance.
+        block: If True, blocks thread with server.wait_for_termination().
+    """
+    server.start()
+    if block:
+        try:
+            server.wait_for_termination()
+        except KeyboardInterrupt:
+            server.stop(grace=5.0)

hexastack_grpc/domain/exceptions.py

@@ -0,0 +1,24 @@
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class GrpcError(HexastackError):
+    """Base exception for all gRPC presentation layer errors.
+
+    Notes/Architectural Intent:
+        Inherits from HexastackError to maintain unified error hierarchy across the framework.
+    """
+
+
+class ServiceRegistrationError(GrpcError):
+    """Exception raised when a gRPC servicer fails registration or lacks a valid add_to_server callback."""
+
+
+class RpcExecutionError(GrpcError):
+    """Exception raised when an RPC handler execution fails during dispatch."""
+
+
+__all__ = [
+    "GrpcError",
+    "RpcExecutionError",
+    "ServiceRegistrationError",
+]

hexastack_grpc/infra/autodiscovery.py

@@ -0,0 +1,64 @@
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+from hexastack_core.infra.autodiscovery import (
+    DiscoveryVisitor,
+    scan_modules,
+)
+from hexastack_grpc.infra.decorators import _GRPC_SERVICE_ATTR
+from hexastack_grpc.infra.registries.service import (
+    GrpcServiceRegistration,
+    GrpcServiceRegistry,
+)
+
+__all__ = [
+    "autodiscover_grpc_services",
+    "create_grpc_visitor",
+]
+
+
+def autodiscover_grpc_services(
+    packages_to_scan: Sequence[str | ModuleType],
+    registry: GrpcServiceRegistry,
+) -> GrpcServiceRegistry:
+    """Discover decorated gRPC servicers from packages.
+
+    Args:
+        packages_to_scan: Sequence of package names or module objects to inspect.
+        registry: Target GrpcServiceRegistry instance.
+
+    Returns:
+        The populated GrpcServiceRegistry instance.
+    """
+    visitor = create_grpc_visitor(registry)
+    scan_modules(packages_to_scan, [visitor])
+    return registry
+
+
+def create_grpc_visitor(
+    registry: GrpcServiceRegistry,
+) -> DiscoveryVisitor:
+    """Create a DiscoveryVisitor callback for single-pass gRPC service discovery.
+
+    Notes/Architectural Intent:
+        Inspects discovered classes and objects for @grpc_service metadata,
+        registering servicers into the supplied service registry during single-pass reflection.
+
+    Args:
+        registry: Target GrpcServiceRegistry instance.
+
+    Returns:
+        DiscoveryVisitor callable accepting (member, module).
+    """
+
+    def visitor(obj: Any, module: ModuleType) -> None:
+        meta: GrpcServiceRegistration | None = getattr(obj, _GRPC_SERVICE_ATTR, None)
+        if meta is not None:
+            registry.register_service(
+                servicer=meta.servicer,
+                add_to_server_fn=meta.add_to_server_fn,
+                service_names=meta.service_names,
+            )
+
+    return visitor

hexastack_grpc/infra/bootstrap.py

@@ -0,0 +1,113 @@
+from dataclasses import dataclass
+
+import grpc
+
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_grpc.infra.autodiscovery import create_grpc_visitor
+from hexastack_grpc.infra.config import (
+    HexastackGrpcConfig,
+    register_grpc_config,
+)
+from hexastack_grpc.infra.decorators import get_grpc_registry
+from hexastack_grpc.infra.interceptors.correlation import (
+    CorrelationServerInterceptor,
+)
+from hexastack_grpc.infra.interceptors.exception import (
+    ExceptionServerInterceptor,
+)
+from hexastack_grpc.infra.interceptors.logging import (
+    LoggingServerInterceptor,
+    TimingServerInterceptor,
+)
+from hexastack_grpc.infra.registries.service import GrpcServiceRegistry
+
+
+@dataclass(frozen=True)
+class GrpcBootstrapResult:
+    """Dataclass holding initialized gRPC server and configuration."""
+
+    config: HexastackGrpcConfig
+    server: grpc.Server
+    registry: GrpcServiceRegistry
+
+
+class GrpcBootstrapper(BootstrapperPort):
+    """Bootstrap extension configuring and building the gRPC server.
+
+    Notes/Architectural Intent:
+        Implements BootstrapperPort with order=40 (executing after CQRS order=20),
+        registering the autodiscovery visitor, compiling the gRPC Server with
+        telemetry interceptors (correlation, exception mapping, logging, timing),
+        and binding it to the DI container.
+    """
+
+    name: str = "grpc"
+    order: int = 40
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Phase 2: Register visitor, assemble gRPC server with interceptors.
+
+        Args:
+            context: BootstrapContext containing DI container, config, and properties.
+
+        Returns:
+            None.
+        """
+        cfg = context.get_config("grpc", HexastackGrpcConfig)
+
+        registry = get_grpc_registry()
+
+        # Register visitor for single-pass reflective scanning (Phase 3)
+        visitor = create_grpc_visitor(registry)
+        context.register_visitor(visitor)
+
+        # 1. Assemble standard interceptors in order
+        interceptors = [
+            CorrelationServerInterceptor(),
+            ExceptionServerInterceptor(),
+            LoggingServerInterceptor(),
+            TimingServerInterceptor(),
+        ]
+
+        # 2. Build grpc.Server instance
+        server = registry.build_server(
+            config=cfg,
+            interceptors=interceptors,
+            container=context.container,
+        )
+
+        # 3. Register Server and Registry into DI container
+        context.container.add_instance(server, declared_class=grpc.Server)
+        context.container.add_instance(registry)
+
+        # 4. Auto-start if configured
+        if cfg.auto_start:
+            server.start()
+
+        # 5. Store in context properties
+        result = GrpcBootstrapResult(
+            config=cfg,
+            server=server,
+            registry=registry,
+        )
+        context.properties["grpc_result"] = result
+        context.properties["grpc_server"] = server
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Phase 1: Register gRPC configuration schema under 'grpc'.
+
+        Args:
+            registry: Target ConfigRegistry instance.
+
+        Returns:
+            None.
+        """
+        register_grpc_config(registry)
+
+
+__all__ = [
+    "GrpcBootstrapper",
+    "GrpcBootstrapResult",
+]

hexastack_grpc/infra/config.py

@@ -0,0 +1,49 @@
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+@config_section("grpc")
+class HexastackGrpcConfig(BaseModel):
+    """Configuration schema for Hexastack gRPC server adapter.
+
+    Notes/Architectural Intent:
+        Configures host binding, port, worker thread pools, and reflection support.
+    """
+
+    host: str = Field(
+        default="0.0.0.0",
+        description="Host interface address to bind the gRPC server to.",
+    )
+    port: int = Field(
+        default=50051,
+        description="Port number to listen for incoming gRPC connections.",
+    )
+    max_workers: int = Field(
+        default=10,
+        description="Maximum worker threads allocated in the gRPC thread pool executor.",
+    )
+    enable_reflection: bool = Field(
+        default=True,
+        description="Enable gRPC Server Reflection protocol for grpcurl and postman discovery.",
+    )
+    auto_start: bool = Field(
+        default=False,
+        description="Automatically start the gRPC server in a background thread on bootstrap.",
+    )
+
+
+__all__ = [
+    "HexastackGrpcConfig",
+    "register_grpc_config",
+]
+
+
+def register_grpc_config(registry: ConfigRegistry) -> None:
+    """Register gRPC configuration schema under 'grpc'.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+    """
+    registry.register_config_section("grpc", HexastackGrpcConfig)

hexastack_grpc/infra/decorators.py

@@ -0,0 +1,62 @@
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from hexastack_grpc.infra.registries.service import (
+    GrpcServiceRegistration,
+    GrpcServiceRegistry,
+)
+
+_GRPC_SERVICE_ATTR = "__hexastack_grpc_service__"
+
+_default_registry = GrpcServiceRegistry()
+
+
+__all__ = [
+    "get_grpc_registry",
+    "grpc_service",
+]
+
+
+def get_grpc_registry() -> GrpcServiceRegistry:
+    """Return the global default GrpcServiceRegistry instance.
+
+    Returns:
+        GrpcServiceRegistry instance.
+    """
+    return _default_registry
+
+
+def grpc_service(
+    add_to_server_fn: Callable[[Any, Any], None],
+    *,
+    service_names: Sequence[str] = (),
+) -> Callable[[Any], Any]:
+    """Decorator registering a gRPC servicer class or instance with its protobuf hook.
+
+    Notes/Architectural Intent:
+        Attaches metadata for single-pass module scanning and registers the servicer
+        in the default GrpcServiceRegistry.
+
+    Args:
+        add_to_server_fn: Generated protobuf hook (e.g. add_UserServiceServicer_to_server).
+        service_names: Optional sequence of full service names for reflection.
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(target: Any) -> Any:
+        meta = GrpcServiceRegistration(
+            servicer=target,
+            add_to_server_fn=add_to_server_fn,
+            service_names=service_names,
+        )
+        setattr(target, _GRPC_SERVICE_ATTR, meta)
+        _default_registry.register_service(
+            servicer=target,
+            add_to_server_fn=add_to_server_fn,
+            service_names=service_names,
+        )
+        return target
+
+    return decorator

hexastack_grpc/infra/dispatch.py

@@ -0,0 +1,101 @@
+import inspect
+from typing import Any
+
+from rodi import Container
+
+from hexastack_core.domain.command import Command
+from hexastack_core.domain.query import Query
+from hexastack_core.utils.inspection import extract_dto_fields
+from hexastack_cqrs.ports.buses import CommandBusPort, QueryBusPort
+
+__all__ = [
+    "dispatch_rpc_command",
+    "dispatch_rpc_command_async",
+    "dispatch_rpc_query",
+    "dispatch_rpc_query_async",
+]
+
+
+def dispatch_rpc_command[C: Command, R](
+    request: Any,
+    command_cls: type[C],
+    container: Container,
+    **extra_kwargs: Any,
+) -> R:
+    """Instantiate and dispatch a Command from a gRPC protobuf request.
+
+    Notes/Architectural Intent:
+        Bridges gRPC RPC handlers to CQRS CommandBusPort with automatic field mapping.
+
+    Args:
+        request: Incoming Protobuf request object.
+        command_cls: Target Command DTO class.
+        container: Active rodi DI Container.
+        **extra_kwargs: Additional parameters overriding request fields.
+
+    Returns:
+        Command execution result.
+    """
+    fields = extract_dto_fields(request, command_cls)
+    fields.update(extra_kwargs)
+    command = command_cls(**fields)
+    bus = container.resolve(CommandBusPort)
+    return bus.dispatch(command)  # type: ignore[return-value]
+
+
+async def dispatch_rpc_command_async[C: Command, R](
+    request: Any,
+    command_cls: type[C],
+    container: Container,
+    **extra_kwargs: Any,
+) -> R:
+    """Asynchronously instantiate and dispatch a Command from a gRPC request."""
+    fields = extract_dto_fields(request, command_cls)
+    fields.update(extra_kwargs)
+    command = command_cls(**fields)
+    bus = container.resolve(CommandBusPort)
+    res = bus.dispatch(command)
+    if inspect.isawaitable(res):
+        res = await res
+    return res  # type: ignore[return-value]
+
+
+def dispatch_rpc_query[Q: Query, R](
+    request: Any,
+    query_cls: type[Q],
+    container: Container,
+    **extra_kwargs: Any,
+) -> R:
+    """Instantiate and dispatch a Query from a gRPC protobuf request.
+
+    Args:
+        request: Incoming Protobuf request object.
+        query_cls: Target Query DTO class.
+        container: Active rodi DI Container.
+        **extra_kwargs: Additional parameters overriding request fields.
+
+    Returns:
+        Query execution result.
+    """
+    fields = extract_dto_fields(request, query_cls)
+    fields.update(extra_kwargs)
+    query = query_cls(**fields)
+    bus = container.resolve(QueryBusPort)
+    return bus.dispatch(query)  # type: ignore[return-value]
+
+
+async def dispatch_rpc_query_async[Q: Query, R](
+    request: Any,
+    query_cls: type[Q],
+    container: Container,
+    **extra_kwargs: Any,
+) -> R:
+    """Asynchronously instantiate and dispatch a Query from a gRPC request."""
+    fields = extract_dto_fields(request, query_cls)
+    fields.update(extra_kwargs)
+    query = query_cls(**fields)
+    bus = container.resolve(QueryBusPort)
+    res = bus.dispatch(query)
+    if inspect.isawaitable(res):
+        res = await res
+    return res  # type: ignore[return-value]

hexastack_grpc/infra/interceptors/correlation.py

@@ -0,0 +1,67 @@
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+
+from hexastack_core.utils.context import (
+    correlation_scope,
+    new_correlation_id,
+)
+from hexastack_grpc.infra.interceptors.generic import (
+    AsyncGenericServerInterceptor,
+    GenericServerInterceptor,
+)
+
+_CORRELATION_METADATA_KEY = "x-correlation-id"
+
+
+class CorrelationServerInterceptor(GenericServerInterceptor):
+    """Synchronous gRPC Server Interceptor for correlation ID propagation.
+
+    Notes/Architectural Intent:
+        Extracts 'x-correlation-id' from incoming gRPC invocation metadata,
+        or generates a fresh UUID4, setting it in ContextVar for the RPC duration.
+    """
+
+    def _handle_unary(
+        self,
+        request: Any,
+        context: grpc.ServicerContext,
+        unary_fn: Callable[[Any, grpc.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Attach a correlation scope for the duration of the unary RPC call."""
+        cid = _extract_cid(handler_call_details.invocation_metadata)
+        with correlation_scope(cid):
+            return unary_fn(request, context)
+
+
+class AsyncCorrelationServerInterceptor(AsyncGenericServerInterceptor):
+    """Asynchronous gRPC Server Interceptor for correlation ID propagation."""
+
+    async def _handle_unary_async(
+        self,
+        request: Any,
+        context: grpc.aio.ServicerContext,
+        unary_fn: Callable[[Any, grpc.aio.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Attach a correlation scope for the duration of the async unary RPC call."""
+        cid = _extract_cid(handler_call_details.invocation_metadata)
+        with correlation_scope(cid):
+            return await unary_fn(request, context)
+
+
+__all__ = [
+    "AsyncCorrelationServerInterceptor",
+    "CorrelationServerInterceptor",
+]
+
+
+def _extract_cid(metadata: Any) -> str:
+    """Extract correlation ID from gRPC invocation metadata or generate fresh UUID."""
+    if metadata:
+        for key, val in metadata:
+            if key.lower() == _CORRELATION_METADATA_KEY:
+                return val.decode("utf-8") if isinstance(val, bytes) else str(val)
+    return new_correlation_id()

hexastack_grpc/infra/interceptors/exception.py

@@ -0,0 +1,78 @@
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+
+from hexastack_core.domain.exceptions import HexastackError
+from hexastack_grpc.infra.interceptors.generic import (
+    AsyncGenericServerInterceptor,
+    GenericServerInterceptor,
+)
+
+
+class ExceptionServerInterceptor(GenericServerInterceptor):
+    """Synchronous gRPC Server Interceptor mapping domain exceptions to gRPC status codes.
+
+    Notes/Architectural Intent:
+        Intercepts unhandled HexastackError domain exceptions and aborts the RPC
+        call with appropriate native gRPC StatusCodes (NOT_FOUND, INVALID_ARGUMENT, etc.).
+    """
+
+    def _handle_unary(
+        self,
+        request: Any,
+        context: grpc.ServicerContext,
+        unary_fn: Callable[[Any, grpc.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Invoke the unary handler, aborting the RPC on any domain exception."""
+        try:
+            return unary_fn(request, context)
+        except Exception as exc:  # noqa: BLE001
+            status_code, details = _map_exception_to_status_code(exc)
+            context.abort(status_code, details)
+
+
+class AsyncExceptionServerInterceptor(AsyncGenericServerInterceptor):
+    """Asynchronous gRPC Server Interceptor mapping domain exceptions to gRPC status codes."""
+
+    async def _handle_unary_async(
+        self,
+        request: Any,
+        context: grpc.aio.ServicerContext,
+        unary_fn: Callable[[Any, grpc.aio.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Invoke the async unary handler, aborting the RPC on any domain exception."""
+        try:
+            return await unary_fn(request, context)
+        except Exception as exc:  # noqa: BLE001
+            status_code, details = _map_exception_to_status_code(exc)
+            await context.abort(status_code, details)
+
+
+__all__ = [
+    "AsyncExceptionServerInterceptor",
+    "ExceptionServerInterceptor",
+]
+
+
+def _map_exception_to_status_code(exc: Exception) -> tuple[grpc.StatusCode, str]:
+    """Map domain exceptions to gRPC status codes and detail messages."""
+    exc_name = type(exc).__name__.lower()
+    msg = str(exc)
+
+    if "notfound" in exc_name:
+        return grpc.StatusCode.NOT_FOUND, msg
+    if "validation" in exc_name or "invalid" in exc_name:
+        return grpc.StatusCode.INVALID_ARGUMENT, msg
+    if "unauthorized" in exc_name or "authentication" in exc_name:
+        return grpc.StatusCode.UNAUTHENTICATED, msg
+    if "forbidden" in exc_name or "permission" in exc_name:
+        return grpc.StatusCode.PERMISSION_DENIED, msg
+    if "conflict" in exc_name or "alreadyexists" in exc_name:
+        return grpc.StatusCode.ALREADY_EXISTS, msg
+    if isinstance(exc, HexastackError):
+        return grpc.StatusCode.INTERNAL, msg
+
+    return grpc.StatusCode.UNKNOWN, msg

hexastack_grpc/infra/interceptors/generic.py

@@ -0,0 +1,180 @@
+"""Generic base classes for synchronous and asynchronous gRPC server interceptors.
+
+Notes/Architectural Intent:
+    Eliminates the repeated handler-resolution, guard, unary extraction, and
+    method-handler rebuild boilerplate that is identical across every concrete
+    interceptor (correlation, exception, logging, timing, etc.).
+
+    Subclasses implement a single abstract method:
+    - ``_handle_unary`` (sync) or ``_handle_unary_async`` (async)
+
+    The base class owns the gRPC plumbing; the subclass owns only its
+    cross-cutting concern.
+
+    Supports ``grpc.ServerInterceptor`` (synchronous) and
+    ``grpc.aio.ServerInterceptor`` (asynchronous) via two separate hierarchies
+    so that typing remains strict and no coroutine/non-coroutine mixing occurs.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+
+
+class GenericServerInterceptor(grpc.ServerInterceptor, ABC):
+    """Abstract base for synchronous unary-unary gRPC server interceptors.
+
+    Notes/Architectural Intent:
+        Owns the repetitive handler-resolution and ``unary_unary`` extraction
+        pattern so concrete subclasses implement only their own cross-cutting
+        concern inside ``_handle_unary``.
+
+        The base transparently passes through handlers for non-unary RPC types
+        (client-streaming, server-streaming, bidi-streaming) so subclasses do
+        not need to handle those cases unless they wish to.
+    """
+
+    @abstractmethod
+    def _handle_unary(
+        self,
+        request: Any,
+        context: grpc.ServicerContext,
+        unary_fn: Callable[[Any, grpc.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Execute the cross-cutting concern around the unary handler invocation.
+
+        Args:
+            request: The deserialized gRPC request message.
+            context: The active ``grpc.ServicerContext`` for this RPC call.
+            unary_fn: The next-in-chain unary handler callable to invoke.
+            handler_call_details: Metadata about the incoming RPC call, including
+                method name and invocation metadata.
+
+        Returns:
+            The response returned by ``unary_fn`` (or a substitute value).
+
+        Raises:
+            Exception: Subclasses may raise, suppress, or re-raise as needed.
+
+        Notes/Architectural Intent:
+            Subclasses must call ``unary_fn(request, context)`` to propagate the
+            call downstream.  They may wrap the call in try/except, prepend or
+            postpend logic, or modify context (e.g. abort) before/after.
+        """
+        ...
+
+    def intercept_service(
+        self,
+        continuation: Callable[[grpc.HandlerCallDetails], grpc.RpcMethodHandler],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler:
+        """Intercept handler resolution, wrapping unary-unary calls.
+
+        Args:
+            continuation: Callable that resolves the next handler in the chain.
+            handler_call_details: Metadata about the incoming RPC call.
+
+        Returns:
+            A (possibly wrapped) ``grpc.RpcMethodHandler``.
+        """
+        handler: Any = continuation(handler_call_details)
+        if handler is None:
+            return handler
+
+        unary_fn = getattr(handler, "unary_unary", None)
+        if unary_fn is None:
+            return handler
+
+        interceptor = self
+
+        def _wrapped(request: Any, context: grpc.ServicerContext) -> Any:
+            return interceptor._handle_unary(
+                request, context, unary_fn, handler_call_details
+            )
+
+        return grpc.unary_unary_rpc_method_handler(
+            _wrapped,
+            request_deserializer=getattr(handler, "request_deserializer", None),
+            response_serializer=getattr(handler, "response_serializer", None),
+        )
+
+
+class AsyncGenericServerInterceptor(grpc.aio.ServerInterceptor, ABC):
+    """Abstract base for asynchronous unary-unary gRPC server interceptors.
+
+    Notes/Architectural Intent:
+        Async counterpart to ``GenericServerInterceptor``. Owns the
+        ``await continuation(...)`` / ``await context.abort(...)`` plumbing so
+        concrete subclasses only implement ``_handle_unary_async``.
+    """
+
+    @abstractmethod
+    async def _handle_unary_async(
+        self,
+        request: Any,
+        context: grpc.aio.ServicerContext,
+        unary_fn: Callable[[Any, grpc.aio.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Execute the cross-cutting concern around the async unary handler invocation.
+
+        Args:
+            request: The deserialized gRPC request message.
+            context: The active ``grpc.aio.ServicerContext`` for this RPC call.
+            unary_fn: The next-in-chain async unary handler coroutine to invoke.
+            handler_call_details: Metadata about the incoming RPC call, including
+                method name and invocation metadata.
+
+        Returns:
+            The response returned by ``await unary_fn(request, context)``.
+
+        Raises:
+            Exception: Subclasses may raise, suppress, or re-raise as needed.
+        """
+        ...
+
+    async def intercept_service(
+        self,
+        continuation: Callable[[grpc.HandlerCallDetails], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Intercept async handler resolution, wrapping unary-unary calls.
+
+        Args:
+            continuation: Async callable that resolves the next handler.
+            handler_call_details: Metadata about the incoming RPC call.
+
+        Returns:
+            A (possibly wrapped) RPC method handler.
+        """
+        handler: Any = await continuation(handler_call_details)
+        if handler is None:
+            return handler
+
+        unary_fn = getattr(handler, "unary_unary", None)
+        if unary_fn is None:
+            return handler
+
+        interceptor = self
+
+        async def _wrapped(request: Any, context: grpc.aio.ServicerContext) -> Any:
+            return await interceptor._handle_unary_async(
+                request, context, unary_fn, handler_call_details
+            )
+
+        return grpc.unary_unary_rpc_method_handler(
+            _wrapped,
+            request_deserializer=getattr(handler, "request_deserializer", None),
+            response_serializer=getattr(handler, "response_serializer", None),
+        )
+
+
+__all__ = [
+    "AsyncGenericServerInterceptor",
+    "GenericServerInterceptor",
+]

hexastack_grpc/infra/interceptors/logging.py

@@ -0,0 +1,63 @@
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+
+from hexastack_grpc.infra.interceptors.generic import GenericServerInterceptor
+
+logger = logging.getLogger("hexastack.grpc")
+
+
+class LoggingServerInterceptor(GenericServerInterceptor):
+    """Synchronous gRPC Server Interceptor for structured RPC logging.
+
+    Notes/Architectural Intent:
+        Logs incoming RPC method calls and completion statuses, capturing exceptions
+        and logging structured error details.
+    """
+
+    def _handle_unary(
+        self,
+        request: Any,
+        context: grpc.ServicerContext,
+        unary_fn: Callable[[Any, grpc.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Log the RPC call start, completion, and any errors."""
+        method = handler_call_details.method
+        logger.info("Handling gRPC call: %s", method)
+        try:
+            res = unary_fn(request, context)
+            logger.info("Completed gRPC call: %s", method)
+            return res
+        except Exception as e:
+            logger.error("Failed gRPC call %s: %s", method, e)
+            raise
+
+
+class TimingServerInterceptor(GenericServerInterceptor):
+    """Synchronous gRPC Server Interceptor for measuring RPC execution latency."""
+
+    def _handle_unary(
+        self,
+        request: Any,
+        context: grpc.ServicerContext,
+        unary_fn: Callable[[Any, grpc.ServicerContext], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> Any:
+        """Measure and log the elapsed time of the unary RPC call."""
+        method = handler_call_details.method
+        start = time.perf_counter()
+        try:
+            return unary_fn(request, context)
+        finally:
+            duration_ms = (time.perf_counter() - start) * 1000
+            logger.debug("RPC %s executed in %.2fms", method, duration_ms)
+
+
+__all__ = [
+    "LoggingServerInterceptor",
+    "TimingServerInterceptor",
+]

hexastack_grpc/infra/registries/service.py

@@ -0,0 +1,133 @@
+from collections.abc import Callable, Sequence
+from concurrent import futures
+from dataclasses import dataclass
+from typing import Any
+
+import grpc
+from rodi import Container
+
+from hexastack_grpc.domain.exceptions import ServiceRegistrationError
+from hexastack_grpc.infra.config import HexastackGrpcConfig
+
+
+@dataclass(frozen=True)
+class GrpcServiceRegistration:
+    """Dataclass holding registered gRPC servicer and its protobuf attachment hook."""
+
+    servicer: Any
+    add_to_server_fn: Callable[[Any, Any], None]
+    service_names: Sequence[str] = ()
+
+
+class GrpcServiceRegistry:
+    """Registry maintaining registered gRPC servicers and compiling the server.
+
+    Notes/Architectural Intent:
+        Compiles registered generated protobuf servicers into a unified grpc.Server,
+        attaching interceptor pipelines and optional Server Reflection.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty gRPC registry."""
+        self._services: list[GrpcServiceRegistration] = []
+
+    def _enable_reflection(
+        self,
+        server: grpc.Server,
+        all_service_names: Sequence[str],
+    ) -> None:
+        """Enable gRPC Server Reflection protocol if package is present."""
+        try:
+            from grpc_reflection.v1alpha import reflection
+
+            names = tuple(all_service_names) + (reflection.SERVICE_NAME,)
+            reflection.enable_server_reflection(names, server)
+        except ImportError:
+            pass
+
+    def _resolve_servicer_instance(
+        self,
+        servicer_val: Any,
+        container: Container | None,
+    ) -> Any:
+        """Resolve or instantiate servicer instance."""
+        if not isinstance(servicer_val, type):
+            return servicer_val
+        if container is not None:
+            try:
+                return container.resolve(servicer_val)
+            except Exception:  # noqa: BLE001
+                return servicer_val()
+        return servicer_val()
+
+    def build_server(
+        self,
+        config: HexastackGrpcConfig,
+        interceptors: Sequence[grpc.ServerInterceptor] | None = None,
+        container: Container | None = None,
+    ) -> grpc.Server:
+        """Construct and populate a grpc.Server instance with registered servicers.
+
+        Args:
+            config: HexastackGrpcConfig options.
+            interceptors: Optional sequence of ServerInterceptor instances.
+            container: Optional rodi DI Container to resolve servicer class dependencies.
+
+        Returns:
+            Configured grpc.Server instance.
+        """
+        thread_pool = futures.ThreadPoolExecutor(max_workers=config.max_workers)
+        server = grpc.server(
+            thread_pool=thread_pool,
+            interceptors=interceptors or (),
+        )
+
+        all_service_names: list[str] = []
+
+        for reg in self._services:
+            servicer_instance = self._resolve_servicer_instance(reg.servicer, container)
+
+            try:
+                reg.add_to_server_fn(servicer_instance, server)
+                all_service_names.extend(reg.service_names)
+            except Exception as e:
+                raise ServiceRegistrationError(
+                    f"Failed to attach {servicer_instance} to gRPC server: {e}"
+                ) from e
+
+        if config.enable_reflection:
+            self._enable_reflection(server, all_service_names)
+
+        server.add_insecure_port(f"{config.host}:{config.port}")
+        return server
+
+    def clear(self) -> None:
+        """Clear all registered services (for test isolation)."""
+        self._services.clear()
+
+    def register_service(
+        self,
+        servicer: Any,
+        add_to_server_fn: Callable[[Any, Any], None],
+        service_names: Sequence[str] = (),
+    ) -> None:
+        """Register a gRPC servicer and its generated add_to_server hook.
+
+        Args:
+            servicer: Servicer instance or class.
+            add_to_server_fn: Generated protobuf hook (e.g. add_GreeterServicer_to_server).
+            service_names: Optional sequence of full service names for reflection.
+        """
+        reg = GrpcServiceRegistration(
+            servicer=servicer,
+            add_to_server_fn=add_to_server_fn,
+            service_names=service_names,
+        )
+        if reg not in self._services:
+            self._services.append(reg)
+
+
+__all__ = [
+    "GrpcServiceRegistration",
+    "GrpcServiceRegistry",
+]

hexastack_grpc-0.0.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.3
+Name: hexastack-grpc
+Version: 0.0.0
+Summary: High-performance gRPC presentation adapter and interceptors for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: grpcio>=1.68.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: protobuf>=5.29.0
+Requires-Dist: grpcio-reflection>=1.68.0 ; extra == 'reflection'
+Requires-Python: >=3.13
+Provides-Extra: reflection
+Description-Content-Type: text/markdown
+
+# hexastack-grpc
+
+> High-performance gRPC presentation adapter, interceptors, and CQRS service integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-grpc` provides a binary RPC presentation adapter for Hexastack applications:
+
+- **Declarative Service Registration (`@grpc_service`)**: Mounts generated protobuf RPC servicers onto the `grpc.Server` with automatic DI resolution.
+- **Cross-Cutting Interceptor Pipeline**:
+  - `CorrelationServerInterceptor`: Propagates `x-correlation-id` from incoming metadata into `ContextVar`.
+  - `LoggingServerInterceptor`: Structured telemetry for RPC method invocations.
+  - `TimingServerInterceptor`: Measures RPC execution latency in milliseconds.
+- **Single-Pass Reflection**: Automatically discovers and registers decorated servicers in Phase 3 module scanning via `create_grpc_visitor`.
+- **gRPC Server Reflection**: Automatically enables gRPC Server Reflection Protocol when `grpcio-reflection` is installed.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_grpc/
+├── domain/          # GrpcError, ServiceRegistrationError, RpcExecutionError
+└── infra/
+    ├── bootstrap.py # GrpcBootstrapper (order=40)
+    ├── config.py    # HexastackGrpcConfig
+    ├── decorators.py# @grpc_service
+    ├── autodiscovery.py # create_grpc_visitor, autodiscover_grpc_services
+    ├── interceptors/# correlation, logging, timing interceptors
+    └── registries/  # service.py (GrpcServiceRegistry)
+```
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph Clients ["gRPC Clients (Microservices, Mobile, Gateway)"]
+        CLIENT["gRPC Protobuf Client"]
+    end
+
+    subgraph GrpcAdapter ["hexastack-grpc"]
+        SERVER["grpc.Server"]
+        INTERCEPTORS["Interceptors (Correlation, Logging, Timing)"]
+        REG["GrpcServiceRegistry"]
+        SERVICER["CQRS Protobuf Servicer"]
+    end
+
+    subgraph CQRSExecution ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    CLIENT --> SERVER
+    SERVER --> INTERCEPTORS
+    INTERCEPTORS --> SERVICER
+    SERVICER -->|dispatches commands| CBUS
+    SERVICER -->|dispatches queries| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container (`rodi`), configuration registry, context variables.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort`.
+- `grpcio>=1.68.0`, `protobuf>=5.29.0`.
+
+### Optional Integrations (Extras)
+- `[reflection]`: Installs `grpcio-reflection>=1.68.0` for runtime service reflection tools (`grpcurl`, Postman).
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone installation
+pip install hexastack-grpc
+
+# With Server Reflection support
+pip install "hexastack-grpc[reflection]"
+
+# Via umbrella package
+pip install "hexastack[grpc]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.grpc]
+host = "0.0.0.0"
+port = 50051
+max_workers = 10
+enable_reflection = true
+auto_start = false
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_grpc.infra.decorators import grpc_service
+
+
+# 1. Define Servicer implementing generated protobuf class
+class GreeterServicer:
+    def SayHello(self, request, context):
+        return HelloReply(message=f"Hello, {request.name}!")
+
+
+# 2. Register Servicer with generated add hook
+@grpc_service(add_GreeterServicer_to_server)
+class GreeterService(GreeterServicer):
+    pass
+
+
+# 3. Bootstrap Runtime and Start Server
+runtime = bootstrap(packages_to_scan=[__name__])
+grpc_server = runtime.get("grpc_server")
+grpc_server.start()
+```

hexastack_grpc-0.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+hexastack_grpc/__init__.py,sha256=xriYulIgr70neOvjzTKco0oP3gAiLEjjL-tv6OYAdnI,109
+hexastack_grpc/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_grpc/adapters/server.py,sha256=uRY_E4GEAbEgtPC5rLYTF1V58pqI5m2hK0XGND_aicE,1168
+hexastack_grpc/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_grpc/domain/exceptions.py,sha256=ZUJ-TRNFXb2B-z3D7DL0odocsJsP-FfPf9Ngw4ychIU,654
+hexastack_grpc/infra/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_grpc/infra/autodiscovery.py,sha256=oxAMcPLvztdQzVt-r2GO6CEAR1dKG1A-bNCQXyZEKeo,1875
+hexastack_grpc/infra/bootstrap.py,sha256=LpvodIFhVUFrwvaKN96kb-pdcokVpWeSGitzgKWonUM,3449
+hexastack_grpc/infra/config.py,sha256=6Mv1LJ1Aq9i3mAuaRbIOCRiug4eIWk-DlNbePkSRQls,1462
+hexastack_grpc/infra/decorators.py,sha256=l2TexzEmSercWrKjUNzhC65XDyxzWQkowBpwL6PPlQ4,1634
+hexastack_grpc/infra/dispatch.py,sha256=lx_LIWXenMbsOHRXS-M2W4UobK0QD2Yt6W92cP31ASM,3045
+hexastack_grpc/infra/interceptors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_grpc/infra/interceptors/correlation.py,sha256=EHAW7xDa_D3rJZ9uNi2nS19rqAEG1o4rCiivO9u5DUA,2232
+hexastack_grpc/infra/interceptors/exception.py,sha256=H8w-A72fnaxcqkPJgsxHaqBfVcO7jbqixMGd_ZgG34w,2873
+hexastack_grpc/infra/interceptors/generic.py,sha256=E6J6n5w46mOticlqx_IJUWD4776dK0Ih6af0ko-4eHs,6580
+hexastack_grpc/infra/interceptors/logging.py,sha256=S-prIyNSjC4-izjWh2mYk59yidD1eQG_XoSPWdfe6s8,1992
+hexastack_grpc/infra/registries/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexastack_grpc/infra/registries/service.py,sha256=IZRGnROI9Xfd0cTQWCgni6t0TFuwzH1b2De5Nfd-iho,4382
+hexastack_grpc-0.0.0.dist-info/WHEEL,sha256=EmLkUISDECbcUx3FMCYOqokNOJqNp2r0d4mJzjErvvs,80
+hexastack_grpc-0.0.0.dist-info/entry_points.txt,sha256=q8_q1a0lSr9Ldxaq-Zg2z-N4TxFN5XXJI2Eao5OJBOQ,82
+hexastack_grpc-0.0.0.dist-info/METADATA,sha256=oAOEoc0PvLF0W2dbs2TzwfGDDHIo71f2otHhOTWBeZQ,4192
+hexastack_grpc-0.0.0.dist-info/RECORD,,

hexastack_grpc-0.0.0.dist-info/WHEEL

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

hexastack_grpc-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[hexastack.bootstrappers]
+grpc = hexastack_grpc.infra.bootstrap:GrpcBootstrapper
+