Add graceful shutdown configuration and handler enhancements

- Introduced `ShutdownConfig` class to encapsulate graceful shutdown settings, including timeout and enabled status.
- Updated `ApplicationConfig` to include `shutdown_config` for managing shutdown behavior.
- Enhanced `GracefulShutdownHandler` to accept timeout parameters and manage shutdown timing.
- Modified `PySpringApplication` to utilize the new shutdown configuration during initialization and shutdown processes.

Author: William-W-Chen

py_spring_core/commons/config_file_template_generator/templates.py

@@ -6,6 +6,7 @@
     "properties_file_path": "./application-properties.json",
     "loguru_config": {"log_file_path": "./logs/app.log", "log_level": "DEBUG"},
     "type_checking_mode": "strict",
+    "shutdown_config": {"timeout_seconds": 30.0, "enabled": True},
 }
 
 app_properties_template: dict[str, Any] = {}

py_spring_core/core/application/application_config.py

@@ -21,6 +21,19 @@ class ServerConfig(BaseModel):
     enabled: bool = Field(default=True)
 
 
+class ShutdownConfig(BaseModel):
+    """
+    Represents the configuration for graceful shutdown.
+
+    Attributes:
+        timeout_seconds: The maximum time in seconds to wait for graceful shutdown before forcing termination.
+        enabled: A boolean flag indicating whether graceful shutdown timeout is enabled.
+    """
+
+    timeout_seconds: float = Field(default=30.0, description="Timeout in seconds for graceful shutdown")
+    enabled: bool = Field(default=True, description="Whether graceful shutdown timeout is enabled")
+
+
 class ApplicationConfig(BaseModel):
     """
     Represents the configuration for the application.
@@ -31,6 +44,7 @@ class ApplicationConfig(BaseModel):
         sqlalchemy_database_uri: The URI for the SQLAlchemy database connection.
         properties_file_path: The file path for the application properties.
         model_file_postfix_patterns: A list of file name patterns for model (for table creation) files.
+        shutdown_config: The configuration for graceful shutdown.
     """
 
     model_config = ConfigDict(protected_namespaces=())
@@ -40,6 +54,7 @@ class ApplicationConfig(BaseModel):
     server_config: ServerConfig
     properties_file_path: str
     loguru_config: LoguruConfig
+    shutdown_config: ShutdownConfig = Field(default_factory=ShutdownConfig)
 
 
 class ApplicationConfigRepository(JsonConfigRepository[ApplicationConfig]):

py_spring_core/core/application/py_spring_application.py

@@ -1,6 +1,6 @@
 import logging
 import os
-from typing import Any, Callable, Iterable, Type
+from typing import Any, Callable, Iterable, Optional, Type
 
 import uvicorn
 from fastapi import APIRouter, FastAPI
@@ -106,6 +106,7 @@ def __init__(
         self.type_checking_service = TypeCheckingService(
             self.app_config.app_src_target_dir
         )
+        self.shutdown_handler: Optional[GracefulShutdownHandler] = None
 
     def __configure_logging(self):
         """Applies the logging configuration using Loguru."""
@@ -292,10 +293,19 @@ def __init_middlewares(self) -> None:
     def __init_graceful_shutdown(self) -> None:
         handler_type = GracefulShutdownHandler.__name__
         logger.debug(f"[{handler_type} INIT] Initialize graceful shutdown...")
-        handler_cls = self._init_external_handler(GracefulShutdownHandler)
+        handler_cls: Optional[Type[GracefulShutdownHandler]] = self._init_external_handler(GracefulShutdownHandler)
         if handler_cls is None:
             return
-        handler_cls()
+        
+        # Get shutdown configuration
+        shutdown_config = self.app_config.shutdown_config
+        logger.debug(f"[{handler_type} INIT] Shutdown timeout: {shutdown_config.timeout_seconds}s, enabled: {shutdown_config.enabled}")
+        
+        # Initialize handler with timeout configuration
+        self.shutdown_handler = handler_cls(
+            timeout_seconds=shutdown_config.timeout_seconds,
+            timeout_enabled=shutdown_config.enabled
+        )
         logger.debug(f"[{handler_type} INIT] Graceful shutdown initialized")
 
     def __configure_uvicorn_logging(self):
@@ -344,4 +354,10 @@ def run(self) -> None:
             if self.app_config.server_config.enabled:
                 self.__run_server()
         finally:
+            # Handle component lifecycle destruction
             self._handle_singleton_components_life_cycle(ComponentLifeCycle.Destruction)
+            # Handle graceful shutdown completion
+            if self.shutdown_handler:
+                self.shutdown_handler.complete_shutdown()
+            
+            

py_spring_core/core/interfaces/graceful_shutdown_handler.py

@@ -2,11 +2,15 @@
 
 from abc import ABC, abstractmethod
 from enum import Enum, auto
+import os
 import signal
 import threading
+import time
 from types import FrameType
 from typing import Optional
 
+from loguru import logger
+
 from py_spring_core.core.interfaces.single_inheritance_required import SingleInheritanceRequired
 
 class ShutdownType(Enum):
@@ -22,9 +26,13 @@ class GracefulShutdownHandler(SingleInheritanceRequired, ABC):
     A mixin class that provides a method to handle graceful shutdown.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, timeout_seconds: float, timeout_enabled: bool) -> None:
         self._shutdown_event = threading.Event()
         self._shutdown_type: Optional[ShutdownType] = None
+        self._timeout_seconds = timeout_seconds
+        self._timeout_enabled = timeout_enabled
+        self._timeout_timer: Optional[threading.Timer] = None
+        self._shutdown_start_time: Optional[float] = None
 
         signal.signal(signal.SIGINT, self._handle_sigint)
         signal.signal(signal.SIGTERM, self._handle_sigterm)
@@ -34,6 +42,7 @@ def _handle_sigint(self, signum: int, frame: Optional[FrameType]) -> None:
             print("[Signal] SIGINT received")
             self._shutdown_type = ShutdownType.MANUAL
             self._shutdown_event.set()
+            self._start_shutdown_timer()
             self.on_shutdown(ShutdownType.MANUAL)
         except Exception as error:
             self.on_error(error)
@@ -43,17 +52,76 @@ def _handle_sigterm(self, signum: int, frame: Optional[FrameType]) -> None:
             print("[Signal] SIGTERM received")
             self._shutdown_type = ShutdownType.SIGTERM
             self._shutdown_event.set()
+            self._start_shutdown_timer()
             self.on_shutdown(ShutdownType.SIGTERM)
         except Exception as error:
             self.on_error(error)
-    
+
+    def _start_shutdown_timer(self) -> None:
+        """Start the shutdown timeout timer if enabled."""
+        if not self._timeout_enabled:
+            return
+            
+        self._shutdown_start_time = time.time()
+        logger.info(f"[Shutdown Timer] Starting shutdown timer for {self._timeout_seconds} seconds")
+        
+        self._timeout_timer = threading.Timer(self._timeout_seconds, self._handle_timeout)
+        self._timeout_timer.daemon = True
+        self._timeout_timer.start()
+
+    def _handle_timeout(self) -> None:
+        """Handle shutdown timeout."""
+        try:
+            if not self._shutdown_event.is_set():
+                return  # Shutdown was not initiated, ignore timeout
+                
+            logger.info(f"[Shutdown Timer] Shutdown timeout reached after {self._timeout_seconds} seconds")
+            self._shutdown_type = ShutdownType.TIMEOUT
+            self.on_timeout()
+        except Exception as error:
+            self.on_error(error)
+        finally:
+            logger.critical("[Shutdown Timer] Timer exited, exiting application")
+            os._exit(0)
+
+    def complete_shutdown(self) -> None:
+        """Mark shutdown as complete and cancel timeout timer."""
+        if self._timeout_timer and self._timeout_timer.is_alive():
+            self._timeout_timer.cancel()
+            
+        if self._shutdown_start_time:
+            elapsed = time.time() - self._shutdown_start_time
+            logger.success(f"[Shutdown Timer] Shutdown completed successfully in {elapsed:.2f} seconds")
 
     def is_shutdown(self) -> bool:
         return self._shutdown_event.is_set()
 
     def get_type(self) -> Optional[ShutdownType]:
         return self._shutdown_type
 
+    def get_timeout_seconds(self) -> float:
+        return self._timeout_seconds
+
+    def is_timeout_enabled(self) -> bool:
+        return self._timeout_enabled
+
+    def get_shutdown_elapsed_time(self) -> Optional[float]:
+        """Get the elapsed time since shutdown started."""
+        if self._shutdown_start_time is None:
+            return None
+        return time.time() - self._shutdown_start_time
+
+    def trigger_manual_shutdown(self, shutdown_type: ShutdownType = ShutdownType.MANUAL) -> None:
+        """Manually trigger shutdown without signal."""
+        try:
+            logger.info(f"[Manual Shutdown] Triggering manual shutdown: {shutdown_type.name}")
+            self._shutdown_type = shutdown_type
+            self._shutdown_event.set()
+            self._start_shutdown_timer()
+            self.on_shutdown(shutdown_type)
+        except Exception as error:
+            self.on_error(error)
+
     @abstractmethod
     def on_shutdown(self, shutdown_type: ShutdownType) -> None:
         """