feat: enhance gRPC integration safety and update dependencies

Author: HosseinNejatiJavaremi

archipy/helpers/utils/keycloak_utils.py

@@ -4,7 +4,15 @@
 from contextvars import ContextVar
 from typing import Any
 
-import grpc
+try:
+    import grpc
+    from grpc import ServicerContext
+    from grpc.aio import ServicerContext as AsyncServicerContext
+
+except ImportError:
+    ServicerContext = None
+    AsyncServicerContext = None
+
 from fastapi import Depends, Request, Security
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import BaseModel
@@ -284,7 +292,7 @@ async def dependency(
         return dependency
 
     @staticmethod
-    def _extract_token_from_metadata(context: grpc.aio.ServicerContext) -> str | None:
+    def _extract_token_from_metadata(context: ServicerContext) -> str | None:
         """Extract Bearer token from gRPC metadata."""
         metadata = dict(context.invocation_metadata())
 
@@ -335,7 +343,7 @@ def grpc_auth(
 
         def decorator(func: Callable) -> Callable:
             @functools.wraps(func)
-            def wrapper(self: object, request: object, context: grpc.ServicerContext) -> object:
+            def wrapper(self: object, request: object, context: ServicerContext) -> object:
                 try:
                     # 1. Extract and validate token
                     token_str = cls._extract_token_from_metadata(context)
@@ -428,7 +436,8 @@ def wrapper(self: object, request: object, context: grpc.ServicerContext) -> obj
                     if isinstance(e, BaseError):
                         e.abort_grpc_sync(context)
                     raise InternalError(
-                        lang=lang, additional_data={"original_error": str(e), "error_type": type(e).__name__}
+                        lang=lang,
+                        additional_data={"original_error": str(e), "error_type": type(e).__name__},
                     ) from e
 
                 finally:
@@ -472,7 +481,7 @@ def async_grpc_auth(
 
         def decorator(func: Callable) -> Callable:
             @functools.wraps(func)
-            async def wrapper(self: object, request: object, context: grpc.aio.ServicerContext) -> object:
+            async def wrapper(self: object, request: object, context: AsyncServicerContext) -> object:
                 try:
                     # 1. Extract and validate token
                     token_str = cls._extract_token_from_metadata(context)
@@ -565,7 +574,8 @@ async def wrapper(self: object, request: object, context: grpc.aio.ServicerConte
                     if isinstance(e, BaseError):
                         await e.abort_grpc_async(context)
                     await InternalError(
-                        lang=lang, additional_data={"original_error": str(e), "error_type": type(e).__name__}
+                        lang=lang,
+                        additional_data={"original_error": str(e), "error_type": type(e).__name__},
                     ).abort_grpc_async(context)
 
                 finally:

archipy/models/errors/base_error.py

@@ -41,7 +41,7 @@ class BaseError(Exception):
     """
 
     http_status_code: ClassVar[int] = 500
-    grpc_status_code: ClassVar[grpc.StatusCode] = grpc.StatusCode.INTERNAL if grpc else 13
+    grpc_status_code: ClassVar[int] = grpc.StatusCode.INTERNAL if grpc else 13
 
     def __init__(
         self,
@@ -178,11 +178,11 @@ def message_fa(self) -> str:
         """
         return self.error_detail.message_fa
 
-    def _get_grpc_status_code(self) -> grpc.StatusCode | int:
+    def _get_grpc_status_code(self) -> int:
         """Gets the proper gRPC status code for this error.
 
         Returns:
-            grpc.StatusCode | int: The gRPC status code enum value or integer code.
+            int: The gRPC status code enum value or integer code.
         """
         if not GRPC_AVAILABLE:
             return 13  # INTERNAL

docs/changelog.md

@@ -2,17 +2,39 @@
 
 All notable changes to ArchiPy are documented in this changelog, organized by version.
 
+## [3.4.4] - 2025-07-17
+
+### Improvements
+
+#### gRPC Integration Improvements
+
+- **Import Safety** - Added robust gRPC import handling with try/except blocks to prevent import errors when gRPC is not
+  available
+- **Type Safety** - Enhanced type annotations for gRPC context handling with improved error type definitions
+- **Error Handling** - Improved gRPC error handling with better type safety and context management
+
+#### Dependency Updates
+
+- **Kafka** - Updated confluent-kafka to version 2.11.0+ for improved stability and performance
+- **Keycloak** - Updated python-keycloak to version 5.7.0+ for enhanced security and features
+- **Sentry** - Updated sentry-sdk to version 2.33.0+ for better error tracking capabilities
+- **MyPy** - Updated MyPy to version 1.17.0+ for improved type checking and Python 3.13 support
+
 ## [3.4.3] - 2025-07-17
 
 ### Improvements
 
 #### Keycloak Security Enhancements
+
 - **Admin Mode Control** - Implemented `IS_ADMIN_MODE_ENABLED` configuration flag to control Keycloak admin operations
-- **Enhanced Security** - Added granular control over admin capabilities allowing authentication-only mode without admin privileges
-- **Principle of Least Privilege** - Updated both synchronous and asynchronous Keycloak adapters to respect admin mode configuration
+- **Enhanced Security** - Added granular control over admin capabilities allowing authentication-only mode without admin
+  privileges
+- **Principle of Least Privilege** - Updated both synchronous and asynchronous Keycloak adapters to respect admin mode
+  configuration
 - **Test Coverage** - Updated BDD test steps to properly handle admin mode configuration for comprehensive testing
 
 ### Security
+
 - **Reduced Attack Surface** - Admin operations can now be disabled while maintaining authentication capabilities
 - **Environment Isolation** - Different environments can have different admin capabilities based on configuration
 - **Audit Trail** - Clear separation between authentication and administrative operations for better security monitoring
@@ -21,7 +43,8 @@ All notable changes to ArchiPy are documented in this changelog, organized by ve
 
 ### Bug Fixes
 
-- **Import Error Resolution** - Fixed critical import errors that were preventing proper module initialization and functionality
+- **Import Error Resolution** - Fixed critical import errors that were preventing proper module initialization and
+  functionality
 
 ## [3.4.1] - 2025-07-07
 
@@ -34,27 +57,42 @@ All notable changes to ArchiPy are documented in this changelog, organized by ve
 ### New Features
 
 #### gRPC Integration Enhancements
-- **Async gRPC Server Interceptors** - Added comprehensive async gRPC server interceptors with enhanced tracing capabilities and metric collection for better observability
-- **Enhanced Authentication Context** - Implemented advanced authentication context management with gRPC decorators for seamless integration
-- **Improved Error Handling** - Enhanced gRPC error handling and context management with better type annotations and error propagation
+
+- **Async gRPC Server Interceptors** - Added comprehensive async gRPC server interceptors with enhanced tracing
+  capabilities and metric collection for better observability
+- **Enhanced Authentication Context** - Implemented advanced authentication context management with gRPC decorators for
+  seamless integration
+- **Improved Error Handling** - Enhanced gRPC error handling and context management with better type annotations and
+  error propagation
 
 #### Keycloak gRPC Authentication
-- **gRPC Authentication Enhancement** - Added token extraction and role validation capabilities for gRPC services with Keycloak integration
-- **Composite Role Management** - Implemented composite role management methods in both KeycloakAdapter and AsyncKeycloakAdapter for advanced authorization scenarios
-- **Streamlined Role Checks** - Enhanced role checking and error handling in KeycloakAdapter for better performance and reliability
+
+- **gRPC Authentication Enhancement** - Added token extraction and role validation capabilities for gRPC services with
+  Keycloak integration
+- **Composite Role Management** - Implemented composite role management methods in both KeycloakAdapter and
+  AsyncKeycloakAdapter for advanced authorization scenarios
+- **Streamlined Role Checks** - Enhanced role checking and error handling in KeycloakAdapter for better performance and
+  reliability
 
 ### Improvements
 
 #### Error Handling & Type Safety
-- **Enhanced Type Annotations** - Updated type annotations in BaseError class for improved gRPC context handling and better type safety
-- **Refined Interceptors** - Improved gRPC server interceptors with better error handling and method name context support
+
+- **Enhanced Type Annotations** - Updated type annotations in BaseError class for improved gRPC context handling and
+  better type safety
+- **Refined Interceptors** - Improved gRPC server interceptors with better error handling and method name context
+  support
 
 #### Code Quality & Performance
-- **DateTime Optimization** - Refactored BaseUtils and UpdatableMixin to use naive local datetime for improved performance and consistency
+
+- **DateTime Optimization** - Refactored BaseUtils and UpdatableMixin to use naive local datetime for improved
+  performance and consistency
 - **Library Updates** - Updated dependencies and libraries for better compatibility and security
 
 ### Community Contributions
-- **Collaborative Development** - Merged contributions from @Mohammadreza-kh94 for Keycloak gRPC authentication enhancements
+
+- **Collaborative Development** - Merged contributions from @Mohammadreza-kh94 for Keycloak gRPC authentication
+  enhancements
 - **Code Refactoring** - Integrated improvements from @heysaeid for datetime handling optimizations
 
 ## [v3.3.1] - 2025-06-12