pydantic-rpc 0.9.0__tar.gz → 0.11.0__tar.gz

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pydantic-rpc
-Version: 0.9.0
+Version: 0.11.0
 Summary: A Python library for building gRPC/ConnectRPC services with Pydantic models.
 Author: Yasushi Itoh
 Requires-Dist: annotated-types==0.7.0
@@ -62,9 +62,10 @@ class OlympicsLocationAgent:
 
 
 if __name__ == "__main__":
-    s = AsyncIOServer()
+    # New enhanced initialization API (optional - backward compatible)
+    s = AsyncIOServer(service=OlympicsLocationAgent(), port=50051)
     loop = asyncio.get_event_loop()
-    loop.run_until_complete(s.run(OlympicsLocationAgent()))
+    loop.run_until_complete(s.run())
 ```
 
 And here is an example of a simple Connect RPC service that exposes the same agent as an ASGI application:
@@ -106,8 +107,8 @@ class OlympicsLocationAgent:
         result = await self._agent.run(req.prompt())
         return result.data
 
-app = ASGIApp()
-app.mount(OlympicsLocationAgent())
+# New enhanced initialization API (optional - backward compatible)
+app = ASGIApp(service=OlympicsLocationAgent())
 
 ```
 
@@ -129,6 +130,17 @@ app.mount(OlympicsLocationAgent())
 - 🛠️ **Pre-generated Protobuf Files and Code:** Pre-generate proto files and corresponding code via the CLI. By setting the environment variable (PYDANTIC_RPC_SKIP_GENERATION), you can skip runtime generation.
 - 🤖 **MCP (Model Context Protocol) Support:** Expose your services as tools for AI assistants using the official MCP SDK, supporting both stdio and HTTP/SSE transports.
 
+## ⚠️ Important Notes for Connect-RPC
+
+When using Connect-RPC with ASGIApp:
+
+- **Endpoint Path Format**: Connect-RPC endpoints use CamelCase method names in the path: `/<package>.<service>/<Method>` (e.g., `/chat.v1.ChatService/SendMessage`)
+- **Content-Type**: Set `Content-Type: application/json` or `application/connect+json` for requests
+- **HTTP/2 Requirement**: Bidirectional streaming requires HTTP/2. Use Hypercorn instead of uvicorn for HTTP/2 support
+- **Testing**: Use [buf curl](https://buf.build/docs/ecosystem/cli/curl) for testing Connect-RPC endpoints with proper streaming support
+
+For detailed examples and testing instructions, see the [examples directory](examples/).
+
 ## 📦 Installation
 
 Install PydanticRPC via pip:
@@ -137,6 +149,54 @@ Install PydanticRPC via pip:
 pip install pydantic-rpc
 ```
 
+For CLI support with built-in server runners:
+
+```bash
+pip install pydantic-rpc-cli  # Includes hypercorn and gunicorn
+```
+
+## 🆕 Enhanced Features (v0.10.0+)
+
+**Note: All new features are fully backward compatible. Existing code continues to work without modification.**
+
+### Enhanced Initialization API
+All server classes now support optional initialization with services:
+
+```python
+# Traditional API (still works)
+server = AsyncIOServer()
+server.set_port(50051)
+await server.run(MyService())
+
+# New enhanced API (optional)
+server = AsyncIOServer(
+    service=MyService(),
+    port=50051,
+    package_name="my.package"
+)
+await server.run()
+
+# Same for ASGI/WSGI apps
+app = ASGIApp(service=MyService(), package_name="my.package")
+```
+
+### Error Handling with Decorators
+Automatically map exceptions to gRPC/Connect status codes:
+
+```python
+from pydantic_rpc import error_handler
+import grpc
+
+class MyService:
+    @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+    @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+    async def get_user(self, request: GetUserRequest) -> User:
+        # Exceptions are automatically converted to proper status codes
+        if request.id not in users_db:
+            raise KeyError(f"User {request.id} not found")
+        return users_db[request.id]
+```
+
 ## 🚀 Getting Started
 
 PydanticRPC supports two main protocols:
@@ -901,8 +961,43 @@ class GoodMessage(Message):
 - Test error cases thoroughly
 - Be aware that errors fail silently
 
+### 🔒 TLS/mTLS Support
+
+PydanticRPC provides built-in support for TLS (Transport Layer Security) and mTLS (mutual TLS) for secure gRPC communication.
+
+```python
+from pydantic_rpc import AsyncIOServer, GrpcTLSConfig, extract_peer_identity
+import grpc
+
+# Basic TLS (server authentication only)
+tls_config = GrpcTLSConfig(
+    cert_chain=server_cert_bytes,
+    private_key=server_key_bytes,
+    require_client_cert=False
+)
+
+# mTLS (mutual authentication)
+tls_config = GrpcTLSConfig(
+    cert_chain=server_cert_bytes,
+    private_key=server_key_bytes,
+    root_certs=ca_cert_bytes,  # CA to verify client certificates
+    require_client_cert=True
+)
+
+# Create server with TLS
+server = AsyncIOServer(tls=tls_config)
+
+# Extract client identity in service methods
+class SecureService:
+    async def secure_method(self, request, context: grpc.ServicerContext):
+        client_identity = extract_peer_identity(context)
+        if client_identity:
+            print(f"Authenticated client: {client_identity}")
+```
+
+For a complete example, see [examples/tls_server.py](examples/tls_server.py) and [examples/tls_client.py](examples/tls_client.py).
+
 ### 🔗 Multiple Services with Custom Interceptors
->>>>>>> origin/main
 
 PydanticRPC supports defining and running multiple gRPC services in a single server:
 
@@ -1055,15 +1150,40 @@ MCP endpoints will be available at:
 - SSE: `GET http://localhost:8000/mcp/sse`
 - Messages: `POST http://localhost:8000/mcp/messages/`
 
-### 🗄️ Protobuf file and code (Python files) generation using CLI
+### 🗄️ CLI Tool (pydantic-rpc-cli)
 
-You can genereate protobuf files and code for a given module and a specified class using `pydantic-rpc` CLI command:
+The CLI tool provides powerful features for generating protobuf files and running servers. Install it separately:
 
 ```bash
-pydantic-rpc a_module.py aClassName
+pip install pydantic-rpc-cli
+```
+
+#### Generate Protobuf Files
+
+```bash
+# Generate .proto file from a service class
+pydantic-rpc generate myapp.services.UserService --output ./proto/
+
+# Also compile to Python code
+pydantic-rpc generate myapp.services.UserService --compile
+```
+
+#### Run Servers Directly
+
+The CLI can run any type of server:
+
+```bash
+# Run as gRPC server (auto-detects async/sync)
+pydantic-rpc serve myapp.services.UserService --port 50051
+
+# Run as Connect-RPC with ASGI (HTTP/2, uses Hypercorn)
+pydantic-rpc serve myapp.services.UserService --asgi --port 8000
+
+# Run as Connect-RPC with WSGI (HTTP/1.1, uses Gunicorn)
+pydantic-rpc serve myapp.services.UserService --wsgi --port 8000 --workers 4
 ```
 
-Using this generated proto file and tools as `protoc`, `buf` and `BSR`, you could generate code for any desired language other than Python.
+Using the generated proto files with tools like `protoc`, `buf` and `BSR`, you can generate code for any desired language.
 
 
 ## 📖 Data Type Mapping

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/README.md

@@ -45,9 +45,10 @@ class OlympicsLocationAgent:
 
 
 if __name__ == "__main__":
-    s = AsyncIOServer()
+    # New enhanced initialization API (optional - backward compatible)
+    s = AsyncIOServer(service=OlympicsLocationAgent(), port=50051)
     loop = asyncio.get_event_loop()
-    loop.run_until_complete(s.run(OlympicsLocationAgent()))
+    loop.run_until_complete(s.run())
 ```
 
 And here is an example of a simple Connect RPC service that exposes the same agent as an ASGI application:
@@ -89,8 +90,8 @@ class OlympicsLocationAgent:
         result = await self._agent.run(req.prompt())
         return result.data
 
-app = ASGIApp()
-app.mount(OlympicsLocationAgent())
+# New enhanced initialization API (optional - backward compatible)
+app = ASGIApp(service=OlympicsLocationAgent())
 
 ```
 
@@ -112,6 +113,17 @@ app.mount(OlympicsLocationAgent())
 - 🛠️ **Pre-generated Protobuf Files and Code:** Pre-generate proto files and corresponding code via the CLI. By setting the environment variable (PYDANTIC_RPC_SKIP_GENERATION), you can skip runtime generation.
 - 🤖 **MCP (Model Context Protocol) Support:** Expose your services as tools for AI assistants using the official MCP SDK, supporting both stdio and HTTP/SSE transports.
 
+## ⚠️ Important Notes for Connect-RPC
+
+When using Connect-RPC with ASGIApp:
+
+- **Endpoint Path Format**: Connect-RPC endpoints use CamelCase method names in the path: `/<package>.<service>/<Method>` (e.g., `/chat.v1.ChatService/SendMessage`)
+- **Content-Type**: Set `Content-Type: application/json` or `application/connect+json` for requests
+- **HTTP/2 Requirement**: Bidirectional streaming requires HTTP/2. Use Hypercorn instead of uvicorn for HTTP/2 support
+- **Testing**: Use [buf curl](https://buf.build/docs/ecosystem/cli/curl) for testing Connect-RPC endpoints with proper streaming support
+
+For detailed examples and testing instructions, see the [examples directory](examples/).
+
 ## 📦 Installation
 
 Install PydanticRPC via pip:
@@ -120,6 +132,54 @@ Install PydanticRPC via pip:
 pip install pydantic-rpc
 ```
 
+For CLI support with built-in server runners:
+
+```bash
+pip install pydantic-rpc-cli  # Includes hypercorn and gunicorn
+```
+
+## 🆕 Enhanced Features (v0.10.0+)
+
+**Note: All new features are fully backward compatible. Existing code continues to work without modification.**
+
+### Enhanced Initialization API
+All server classes now support optional initialization with services:
+
+```python
+# Traditional API (still works)
+server = AsyncIOServer()
+server.set_port(50051)
+await server.run(MyService())
+
+# New enhanced API (optional)
+server = AsyncIOServer(
+    service=MyService(),
+    port=50051,
+    package_name="my.package"
+)
+await server.run()
+
+# Same for ASGI/WSGI apps
+app = ASGIApp(service=MyService(), package_name="my.package")
+```
+
+### Error Handling with Decorators
+Automatically map exceptions to gRPC/Connect status codes:
+
+```python
+from pydantic_rpc import error_handler
+import grpc
+
+class MyService:
+    @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+    @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+    async def get_user(self, request: GetUserRequest) -> User:
+        # Exceptions are automatically converted to proper status codes
+        if request.id not in users_db:
+            raise KeyError(f"User {request.id} not found")
+        return users_db[request.id]
+```
+
 ## 🚀 Getting Started
 
 PydanticRPC supports two main protocols:
@@ -884,8 +944,43 @@ class GoodMessage(Message):
 - Test error cases thoroughly
 - Be aware that errors fail silently
 
+### 🔒 TLS/mTLS Support
+
+PydanticRPC provides built-in support for TLS (Transport Layer Security) and mTLS (mutual TLS) for secure gRPC communication.
+
+```python
+from pydantic_rpc import AsyncIOServer, GrpcTLSConfig, extract_peer_identity
+import grpc
+
+# Basic TLS (server authentication only)
+tls_config = GrpcTLSConfig(
+    cert_chain=server_cert_bytes,
+    private_key=server_key_bytes,
+    require_client_cert=False
+)
+
+# mTLS (mutual authentication)
+tls_config = GrpcTLSConfig(
+    cert_chain=server_cert_bytes,
+    private_key=server_key_bytes,
+    root_certs=ca_cert_bytes,  # CA to verify client certificates
+    require_client_cert=True
+)
+
+# Create server with TLS
+server = AsyncIOServer(tls=tls_config)
+
+# Extract client identity in service methods
+class SecureService:
+    async def secure_method(self, request, context: grpc.ServicerContext):
+        client_identity = extract_peer_identity(context)
+        if client_identity:
+            print(f"Authenticated client: {client_identity}")
+```
+
+For a complete example, see [examples/tls_server.py](examples/tls_server.py) and [examples/tls_client.py](examples/tls_client.py).
+
 ### 🔗 Multiple Services with Custom Interceptors
->>>>>>> origin/main
 
 PydanticRPC supports defining and running multiple gRPC services in a single server:
 
@@ -1038,15 +1133,40 @@ MCP endpoints will be available at:
 - SSE: `GET http://localhost:8000/mcp/sse`
 - Messages: `POST http://localhost:8000/mcp/messages/`
 
-### 🗄️ Protobuf file and code (Python files) generation using CLI
+### 🗄️ CLI Tool (pydantic-rpc-cli)
 
-You can genereate protobuf files and code for a given module and a specified class using `pydantic-rpc` CLI command:
+The CLI tool provides powerful features for generating protobuf files and running servers. Install it separately:
 
 ```bash
-pydantic-rpc a_module.py aClassName
+pip install pydantic-rpc-cli
+```
+
+#### Generate Protobuf Files
+
+```bash
+# Generate .proto file from a service class
+pydantic-rpc generate myapp.services.UserService --output ./proto/
+
+# Also compile to Python code
+pydantic-rpc generate myapp.services.UserService --compile
+```
+
+#### Run Servers Directly
+
+The CLI can run any type of server:
+
+```bash
+# Run as gRPC server (auto-detects async/sync)
+pydantic-rpc serve myapp.services.UserService --port 50051
+
+# Run as Connect-RPC with ASGI (HTTP/2, uses Hypercorn)
+pydantic-rpc serve myapp.services.UserService --asgi --port 8000
+
+# Run as Connect-RPC with WSGI (HTTP/1.1, uses Gunicorn)
+pydantic-rpc serve myapp.services.UserService --wsgi --port 8000 --workers 4
 ```
 
-Using this generated proto file and tools as `protoc`, `buf` and `BSR`, you could generate code for any desired language other than Python.
+Using the generated proto files with tools like `protoc`, `buf` and `BSR`, you can generate code for any desired language.
 
 
 ## 📖 Data Type Mapping

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-rpc"
-version = "0.9.0"
+version = "0.11.0"
 description = "A Python library for building gRPC/ConnectRPC services with Pydantic models."
 authors = [
     { name = "Yasushi Itoh" }
@@ -19,8 +19,6 @@ dependencies = [
 readme = "README.md"
 requires-python = ">= 3.11"
 
-[project.scripts]
-pydantic-rpc = "pydantic_rpc.core:main"
 
 [build-system]
 requires = ["uv_build>=0.7.21,<0.8.0"]

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/__init__.py

@@ -13,6 +13,13 @@ from .decorators import (
     proto_option,
     get_method_options,
     has_http_option,
+    error_handler,
+    get_error_handlers,
+)
+from .tls import (
+    GrpcTLSConfig,
+    extract_peer_identity,
+    extract_peer_certificate_chain,
 )
 
 __all__ = [
@@ -26,6 +33,11 @@ __all__ = [
     "proto_option",
     "get_method_options",
     "has_http_option",
+    "error_handler",
+    "get_error_handlers",
+    "GrpcTLSConfig",
+    "extract_peer_identity",
+    "extract_peer_certificate_chain",
 ]
 
 # Optional MCP support

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/core.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from posixpath import basename
 from typing import (
     Any,
+    Optional,
     TypeAlias,
     get_args,
     get_origin,
@@ -36,6 +37,7 @@ from grpc_reflection.v1alpha import reflection
 from grpc_tools import protoc
 from pydantic import BaseModel, ValidationError
 from .decorators import get_method_options, has_http_option
+from .tls import GrpcTLSConfig
 
 ###############################################################################
 # 1. Message definitions & converter extensions
@@ -2602,13 +2604,23 @@ def generate_combined_descriptor_set(
 class Server:
     """A simple gRPC server that uses ThreadPoolExecutor for concurrency."""
 
-    def __init__(self, max_workers: int = 8, *interceptors: Any) -> None:
+    def __init__(
+        self,
+        service: Optional[object] = None,
+        port: int = 50051,
+        package_name: str = "",
+        max_workers: int = 8,
+        *interceptors: Any,
+        tls: Optional["GrpcTLSConfig"] = None,
+    ) -> None:
         self._server: grpc.Server = grpc.server(
             futures.ThreadPoolExecutor(max_workers), interceptors=interceptors
         )
         self._service_names: list[str] = []
-        self._package_name: str = ""
-        self._port: int = 50051
+        self._package_name: str = package_name
+        self._port: int = port
+        self._tls_config = tls
+        self._initial_service = service
 
     def set_package_name(self, package_name: str):
         """Set the package name for .proto generation."""
@@ -2646,6 +2658,11 @@ class Server:
         Mount multiple services and run the gRPC server with reflection and health check.
         Press Ctrl+C or send SIGTERM to stop.
         """
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2658,7 +2675,16 @@ class Server:
         health_pb2_grpc.add_HealthServicer_to_server(health_servicer, self._server)
         reflection.enable_server_reflection(SERVICE_NAMES, self._server)
 
-        self._server.add_insecure_port(f"[::]:{self._port}")
+        if self._tls_config:
+            # Use secure port with TLS
+            credentials = self._tls_config.to_server_credentials()
+            self._server.add_secure_port(f"[::]:{self._port}", credentials)
+            print(f"gRPC server starting with TLS on port {self._port}...")
+        else:
+            # Use insecure port
+            self._server.add_insecure_port(f"[::]:{self._port}")
+            print(f"gRPC server starting on port {self._port}...")
+
         self._server.start()
 
         def handle_signal(signum: signal.Signals, frame: Any):
@@ -2680,11 +2706,20 @@ class Server:
 class AsyncIOServer:
     """An async gRPC server using asyncio."""
 
-    def __init__(self, *interceptors: grpc.ServerInterceptor) -> None:
+    def __init__(
+        self,
+        service: Optional[object] = None,
+        port: int = 50051,
+        package_name: str = "",
+        *interceptors: grpc.ServerInterceptor,
+        tls: Optional["GrpcTLSConfig"] = None,
+    ) -> None:
         self._server: grpc.aio.Server = grpc.aio.server(interceptors=interceptors)
         self._service_names: list[str] = []
-        self._package_name: str = ""
-        self._port: int = 50051
+        self._package_name: str = package_name
+        self._port: int = port
+        self._tls_config = tls
+        self._initial_service = service
 
     def set_package_name(self, package_name: str):
         """Set the package name for .proto generation."""
@@ -2724,6 +2759,11 @@ class AsyncIOServer:
         Mount multiple async services and run the gRPC server with reflection and health check.
         Press Ctrl+C or send SIGTERM to stop.
         """
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2736,7 +2776,16 @@ class AsyncIOServer:
         health_pb2_grpc.add_HealthServicer_to_server(health_servicer, self._server)
         reflection.enable_server_reflection(SERVICE_NAMES, self._server)
 
-        _ = self._server.add_insecure_port(f"[::]:{self._port}")
+        if self._tls_config:
+            # Use secure port with TLS
+            credentials = self._tls_config.to_server_credentials()
+            _ = self._server.add_secure_port(f"[::]:{self._port}", credentials)
+            print(f"gRPC server starting with TLS on port {self._port}...")
+        else:
+            # Use insecure port
+            _ = self._server.add_insecure_port(f"[::]:{self._port}")
+            print(f"gRPC server starting on port {self._port}...")
+
         await self._server.start()
 
         shutdown_event = asyncio.Event()
@@ -2771,10 +2820,11 @@ class ASGIApp:
     An ASGI-compatible application that can serve Connect-RPC via Connecpy.
     """
 
-    def __init__(self):
+    def __init__(self, service: Optional[object] = None, package_name: str = ""):
         self._services: list[tuple[Any, str]] = []  # List of (app, path) tuples
         self._service_names: list[str] = []
-        self._package_name: str = ""
+        self._package_name: str = package_name
+        self._initial_service = service
 
     def mount(self, obj: object, package_name: str = ""):
         """Generate and compile proto files, then mount the async service implementation."""
@@ -2807,6 +2857,11 @@ class ASGIApp:
 
     def mount_objs(self, *objs: object):
         """Mount multiple service objects into this ASGI app."""
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2817,6 +2872,10 @@ class ASGIApp:
         send: Callable[[dict[str, Any]], Any],
     ):
         """ASGI entry point with routing for multiple services."""
+        # Mount initial service on first call if not already mounted
+        if self._initial_service and not self._services:
+            self.mount(self._initial_service, self._package_name)
+
         if scope["type"] != "http":
             await send({"type": "http.response.start", "status": 404})
             await send({"type": "http.response.body", "body": b"Not Found"})
@@ -2843,10 +2902,11 @@ class WSGIApp:
     A WSGI-compatible application that can serve Connect-RPC via Connecpy.
     """
 
-    def __init__(self):
+    def __init__(self, service: Optional[object] = None, package_name: str = ""):
         self._services: list[tuple[Any, str]] = []  # List of (app, path) tuples
         self._service_names: list[str] = []
-        self._package_name: str = ""
+        self._package_name: str = package_name
+        self._initial_service = service
 
     def mount(self, obj: object, package_name: str = ""):
         """Generate and compile proto files, then mount the sync service implementation."""
@@ -2879,6 +2939,11 @@ class WSGIApp:
 
     def mount_objs(self, *objs: object):
         """Mount multiple service objects into this WSGI app."""
+        # Mount initial service if provided
+        if self._initial_service:
+            self.mount(self._initial_service, self._package_name)
+
+        # Mount additional services
         for obj in objs:
             self.mount(obj, self._package_name)
 
@@ -2890,6 +2955,10 @@ class WSGIApp:
         ],
     ) -> Iterable[bytes]:
         """WSGI entry point with routing for multiple services."""
+        # Mount initial service on first call if not already mounted
+        if self._initial_service and not self._services:
+            self.mount(self._initial_service, self._package_name)
+
         path = environ.get("PATH_INFO", "")
 
         # Route to the appropriate service based on path

{pydantic_rpc-0.9.0 → pydantic_rpc-0.11.0}/src/pydantic_rpc/decorators.py

@@ -1,12 +1,15 @@
 """Decorators for adding protobuf options to RPC methods."""
 
-from typing import Any, Callable, Dict, List, Optional, TypeVar
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Type
 from functools import wraps
+import grpc
+from connecpy.code import Code as ConnectErrors
 
 from .options import OptionMetadata, OPTION_METADATA_ATTR
 
 
 F = TypeVar("F", bound=Callable[..., Any])
+ERROR_HANDLER_ATTR = "__pydantic_rpc_error_handlers__"
 
 
 def http_option(
@@ -136,3 +139,71 @@ def has_proto_options(method: Callable) -> bool:
     """
     metadata = get_method_options(method)
     return metadata is not None and len(metadata.proto_options) > 0
+
+
+def error_handler(
+    exception_type: Type[Exception],
+    status_code: Optional[grpc.StatusCode] = None,
+    connect_code: Optional[ConnectErrors] = None,
+    handler: Optional[Callable[[Exception], tuple[str, Any]]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator to add automatic error handling to an RPC method.
+
+    Args:
+        exception_type: The type of exception to handle
+        status_code: The gRPC status code to return (for gRPC services)
+        connect_code: The Connect error code to return (for Connect services)
+        handler: Optional custom handler function that returns (message, details)
+
+    Example:
+        @error_handler(ValidationError, status_code=grpc.StatusCode.INVALID_ARGUMENT)
+        @error_handler(KeyError, status_code=grpc.StatusCode.NOT_FOUND)
+        async def get_user(self, request: GetUserRequest) -> User:
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        # Get or create error handlers list
+        if not hasattr(func, ERROR_HANDLER_ATTR):
+            setattr(func, ERROR_HANDLER_ATTR, [])
+
+        handlers = getattr(func, ERROR_HANDLER_ATTR)
+
+        # Add this handler to the list
+        handlers.append(
+            {
+                "exception_type": exception_type,
+                "status_code": status_code or grpc.StatusCode.INTERNAL,
+                "connect_code": connect_code or ConnectErrors.INTERNAL,
+                "handler": handler,
+            }
+        )
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve the error handlers on the wrapper
+        setattr(wrapper, ERROR_HANDLER_ATTR, handlers)
+
+        # Preserve any existing option metadata
+        if hasattr(func, OPTION_METADATA_ATTR):
+            setattr(wrapper, OPTION_METADATA_ATTR, getattr(func, OPTION_METADATA_ATTR))
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def get_error_handlers(method: Callable) -> Optional[List[Dict[str, Any]]]:
+    """
+    Get error handlers from a method.
+
+    Args:
+        method: The method to get error handlers from
+
+    Returns:
+        List of error handler configurations if present, None otherwise
+    """
+    return getattr(method, ERROR_HANDLER_ATTR, None)

pydantic_rpc-0.11.0/src/pydantic_rpc/tls.py

@@ -0,0 +1,96 @@
+"""TLS configuration for gRPC servers."""
+
+from dataclasses import dataclass
+from typing import Optional, Any
+import grpc
+
+
+@dataclass
+class GrpcTLSConfig:
+    """Configuration for gRPC server TLS.
+
+    Args:
+        cert_chain: The PEM-encoded server certificate chain.
+        private_key: The PEM-encoded private key for the server certificate.
+        root_certs: Optional PEM-encoded root certificates for verifying client certificates.
+                   If provided with require_client_cert=True, enables mTLS.
+        require_client_cert: If True, requires and verifies client certificates (mTLS).
+    """
+
+    cert_chain: bytes
+    private_key: bytes
+    root_certs: Optional[bytes] = None
+    require_client_cert: bool = False
+
+    def to_server_credentials(self) -> grpc.ServerCredentials:
+        """Convert to gRPC ServerCredentials."""
+        private_key_certificate_chain_pairs = [(self.private_key, self.cert_chain)]
+
+        if self.require_client_cert and self.root_certs:
+            # mTLS: require and verify client certificates
+            return grpc.ssl_server_credentials(
+                private_key_certificate_chain_pairs,
+                root_certificates=self.root_certs,
+                require_client_auth=True,
+            )
+        elif self.root_certs:
+            # Optional client certificates
+            return grpc.ssl_server_credentials(
+                private_key_certificate_chain_pairs,
+                root_certificates=self.root_certs,
+                require_client_auth=False,
+            )
+        else:
+            # Server TLS only, no client certificate validation
+            return grpc.ssl_server_credentials(private_key_certificate_chain_pairs)
+
+
+def extract_peer_identity(context: grpc.ServicerContext) -> Optional[str]:
+    """Extract the peer identity from the ServicerContext.
+
+    For mTLS connections, this returns the client's certificate subject.
+
+    Args:
+        context: The gRPC ServicerContext from a request handler.
+
+    Returns:
+        The peer identity string if available, None otherwise.
+    """
+    auth_context: Any = context.auth_context()
+    if auth_context:
+        # The peer identity is typically stored under the 'x509_common_name' key
+        # or 'x509_subject_alternative_name' for SANs
+        identities = auth_context.get("x509_common_name")
+        if identities and len(identities) > 0:
+            # Return the first identity (there's usually only one CN)
+            # gRPC returns bytes, so we decode to string
+            identity_bytes: bytes = identities[0]
+            return identity_bytes.decode("utf-8")
+
+        # Fallback to SAN if CN is not available
+        san_identities = auth_context.get("x509_subject_alternative_name")
+        if san_identities and len(san_identities) > 0:
+            # gRPC returns bytes, so we decode to string
+            san_bytes: bytes = san_identities[0]
+            return san_bytes.decode("utf-8")
+
+    return None
+
+
+def extract_peer_certificate_chain(context: grpc.ServicerContext) -> Optional[bytes]:
+    """Extract the peer's certificate chain from the ServicerContext.
+
+    Args:
+        context: The gRPC ServicerContext from a request handler.
+
+    Returns:
+        The peer's certificate chain in PEM format if available, None otherwise.
+    """
+    auth_context: Any = context.auth_context()
+    if auth_context:
+        cert_chain = auth_context.get("x509_peer_certificate")
+        if cert_chain and len(cert_chain) > 0:
+            cert_bytes: bytes = cert_chain[0]
+            return cert_bytes
+
+    return None