hexastack-grpc 0.0.0__tar.gz

hexastack_grpc-0.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,127 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "hexastack-grpc"
+version = "0.0.0"
+description = "High-performance gRPC presentation adapter and interceptors for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "grpcio>=1.68.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "protobuf>=5.29.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+reflection = ["grpcio-reflection>=1.68.0"]
+
+[project.entry-points."hexastack.bootstrappers"]
+grpc = "hexastack_grpc.infra.bootstrap:GrpcBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_grpc"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_grpc"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_grpc.domain"]
+forbidden_modules = [
+    "hexastack_grpc.adapters",
+    "hexastack_grpc.infra",
+]

hexastack_grpc-0.0.0/pyproject.toml.orig

@@ -0,0 +1,52 @@
+[project]
+name = "hexastack-grpc"
+version = "0.0.0"
+description = "High-performance gRPC presentation adapter and interceptors for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "grpcio>=1.68.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "protobuf>=5.29.0",
+]
+
+[project.optional-dependencies]
+reflection = [
+    "grpcio-reflection>=1.68.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+grpc = "hexastack_grpc.infra.bootstrap:GrpcBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_grpc"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_grpc"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_grpc.domain"]
+forbidden_modules = [
+    "hexastack_grpc.adapters",
+    "hexastack_grpc.infra",
+]

hexastack_grpc-0.0.0/src/hexastack_grpc/__init__.py

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

hexastack_grpc-0.0.0/src/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-0.0.0/src/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-0.0.0/src/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-0.0.0/src/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-0.0.0/src/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)