csctracker-py-core 26.37.2__tar.gz → 26.37.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/PKG-INFO +46 -3
  2. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/README.md +45 -2
  3. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/models/emuns/config.py +1 -0
  4. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/starter.py +10 -0
  5. csctracker_py_core-26.37.4/csctracker_py_core/utils/graceful_shutdown.py +146 -0
  6. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/interceptor.py +6 -1
  7. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core.egg-info/PKG-INFO +46 -3
  8. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core.egg-info/SOURCES.txt +3 -1
  9. csctracker_py_core-26.37.4/tests/test_graceful_shutdown.py +131 -0
  10. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/LICENSE +0 -0
  11. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/__init__.py +0 -0
  12. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/models/__init__.py +0 -0
  13. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/models/emuns/__init__.py +0 -0
  14. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/repository/__init__.py +0 -0
  15. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/repository/http_repository.py +0 -0
  16. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/repository/remote_repository.py +0 -0
  17. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/__init__.py +0 -0
  18. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/configs.py +0 -0
  19. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/request_info.py +0 -0
  20. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/utils.py +0 -0
  21. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core/utils/version.py +0 -0
  22. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core.egg-info/dependency_links.txt +0 -0
  23. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core.egg-info/requires.txt +0 -0
  24. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/csctracker_py_core.egg-info/top_level.txt +0 -0
  25. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/setup.cfg +0 -0
  26. {csctracker_py_core-26.37.2 → csctracker_py_core-26.37.4}/setup.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: csctracker-py-core
3
- Version: 26.37.2
3
+ Version: 26.37.4
4
4
  Summary: A base library for microservices with Flask, JSON logging, and Prometheus telemetry.
5
5
  Home-page: https://github.com/krlsedu/CscTrackerPyCore
6
6
  Author: Carlos Eduardo
@@ -66,6 +66,7 @@ CscTrackerPyCore é uma biblioteca Python base desenvolvida para padronizar e ac
66
66
  - **Interceptor de Requisições**: Registro detalhado de chamadas HTTP (método, path, status, duração) com opção de persistência remota para auditoria.
67
67
  - **Documentação Automática**: Geração de especificação **Swagger (OpenAPI)** simplificada.
68
68
  - **Processamento em Background**: Integração com `csctracker-queue-scheduler` para execução de tarefas assíncronas e agendadas.
69
+ - **Graceful Shutdown para Docker Swarm**: Encerramento controlado em rolling updates, aguardando término de requisições HTTP e esvaziamento total da fila do scheduler antes do encerramento do processo.
69
70
  - **Repositórios Remotos**: Abstração para comunicação entre serviços via HTTP com tratamento de headers e correlação.
70
71
 
71
72
  ## Requisitos
@@ -107,6 +108,7 @@ A biblioteca é configurada principalmente via variáveis de ambiente, suportand
107
108
  | `LOG_RESPONSE_BODY` | Se `True`, inclui o corpo da resposta nos logs | `False` |
108
109
  | `URL_BFF` | URL base para persistência de logs de requisição | `http://api-gateway/` |
109
110
  | `API_TOKEN` | Token de autorização para chamadas externas | `seu_token_aqui` |
111
+ | `SHUTDOWN_TIMEOUT` | Tempo limite (segundos) para conclusão de requisições e tarefas em background durante o shutdown | `30` |
110
112
  | `DEBUG` | Ativa o modo debug do Flask se definido como `1` | `0` |
111
113
 
112
114
  ## Uso Didático
@@ -144,11 +146,52 @@ Uma vez iniciado o `Starter`, todos os logs do sistema usarão o formato JSON e
144
146
  http_repo = starter.get_http_repository()
145
147
  ```
146
148
 
149
+ ### 4. Graceful Shutdown e Ganchos Customizados
150
+
151
+ Ao receber sinais como `SIGTERM` (pelo Docker Swarm) ou `SIGINT` (Ctrl+C), a aplicação:
152
+ 1. Aguarda a finalização de todas as requisições HTTP ativas.
153
+ 2. Aguarda o esvaziamento completo e processamento da fila do `SchedulerService`.
154
+ 3. Executa ganchos de limpeza customizados registrados via `starter.register_shutdown_hook(...)`.
155
+ 4. Finaliza o processo com segurança respeitando o `SHUTDOWN_TIMEOUT`.
156
+
157
+ ```python
158
+ def cleanup_resources():
159
+ print("Fechando conexões e pools externos...")
160
+
161
+ starter.register_shutdown_hook(cleanup_resources)
162
+ ```
163
+
164
+ ## Implantação no Docker Swarm
165
+
166
+ Para garantir atualizações contínuas (*rolling updates zero-downtime*), configure o `docker-compose.yml` da stack no Swarm utilizando `order: start-first` e defina `stop_grace_period` com um valor superior ao `SHUTDOWN_TIMEOUT`:
167
+
168
+ ```yaml
169
+ version: "3.8"
170
+
171
+ services:
172
+ notification-ai:
173
+ image: krlsedu/csctracker-notification-ai:26.37.002
174
+ stop_grace_period: 45s # Superior ao SHUTDOWN_TIMEOUT da aplicação
175
+ environment:
176
+ - SHUTDOWN_TIMEOUT=30
177
+ - URL_REPOSITORY=http://bff:8080/repository-clickhouse/
178
+ - URL_BFF=http://bff:8080/
179
+ networks:
180
+ - swarm_network
181
+ deploy:
182
+ replicas: 2
183
+ update_config:
184
+ parallelism: 1
185
+ delay: 10s
186
+ order: start-first
187
+ ```
188
+
147
189
  ## Estrutura do Projeto
148
190
 
149
- - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas e Swagger.
191
+ - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas, Swagger e Graceful Shutdown.
150
192
  - `Configs`: Gerencia o carregamento de variáveis de ambiente e a configuração do logger JSON.
151
- - `Interceptor`: Middleware Flask que captura dados de performance e logs de entrada/saída.
193
+ - `GracefulShutdown`: Gerenciador de encerramento suave e sincronização de tarefas/requisições.
194
+ - `Interceptor`: Middleware Flask que captura dados de performance, telemetria e controla requisições ativas.
152
195
  - `HttpRepository`: Facilita requisições HTTP externas com injeção de headers de segurança e rastreio.
153
196
  - `RequestInfo`: Utilitário para gerenciar IDs de correlação (Correlation IDs) entre threads.
154
197
 
@@ -16,6 +16,7 @@ CscTrackerPyCore é uma biblioteca Python base desenvolvida para padronizar e ac
16
16
  - **Interceptor de Requisições**: Registro detalhado de chamadas HTTP (método, path, status, duração) com opção de persistência remota para auditoria.
17
17
  - **Documentação Automática**: Geração de especificação **Swagger (OpenAPI)** simplificada.
18
18
  - **Processamento em Background**: Integração com `csctracker-queue-scheduler` para execução de tarefas assíncronas e agendadas.
19
+ - **Graceful Shutdown para Docker Swarm**: Encerramento controlado em rolling updates, aguardando término de requisições HTTP e esvaziamento total da fila do scheduler antes do encerramento do processo.
19
20
  - **Repositórios Remotos**: Abstração para comunicação entre serviços via HTTP com tratamento de headers e correlação.
20
21
 
21
22
  ## Requisitos
@@ -57,6 +58,7 @@ A biblioteca é configurada principalmente via variáveis de ambiente, suportand
57
58
  | `LOG_RESPONSE_BODY` | Se `True`, inclui o corpo da resposta nos logs | `False` |
58
59
  | `URL_BFF` | URL base para persistência de logs de requisição | `http://api-gateway/` |
59
60
  | `API_TOKEN` | Token de autorização para chamadas externas | `seu_token_aqui` |
61
+ | `SHUTDOWN_TIMEOUT` | Tempo limite (segundos) para conclusão de requisições e tarefas em background durante o shutdown | `30` |
60
62
  | `DEBUG` | Ativa o modo debug do Flask se definido como `1` | `0` |
61
63
 
62
64
  ## Uso Didático
@@ -94,11 +96,52 @@ Uma vez iniciado o `Starter`, todos os logs do sistema usarão o formato JSON e
94
96
  http_repo = starter.get_http_repository()
95
97
  ```
96
98
 
99
+ ### 4. Graceful Shutdown e Ganchos Customizados
100
+
101
+ Ao receber sinais como `SIGTERM` (pelo Docker Swarm) ou `SIGINT` (Ctrl+C), a aplicação:
102
+ 1. Aguarda a finalização de todas as requisições HTTP ativas.
103
+ 2. Aguarda o esvaziamento completo e processamento da fila do `SchedulerService`.
104
+ 3. Executa ganchos de limpeza customizados registrados via `starter.register_shutdown_hook(...)`.
105
+ 4. Finaliza o processo com segurança respeitando o `SHUTDOWN_TIMEOUT`.
106
+
107
+ ```python
108
+ def cleanup_resources():
109
+ print("Fechando conexões e pools externos...")
110
+
111
+ starter.register_shutdown_hook(cleanup_resources)
112
+ ```
113
+
114
+ ## Implantação no Docker Swarm
115
+
116
+ Para garantir atualizações contínuas (*rolling updates zero-downtime*), configure o `docker-compose.yml` da stack no Swarm utilizando `order: start-first` e defina `stop_grace_period` com um valor superior ao `SHUTDOWN_TIMEOUT`:
117
+
118
+ ```yaml
119
+ version: "3.8"
120
+
121
+ services:
122
+ notification-ai:
123
+ image: krlsedu/csctracker-notification-ai:26.37.002
124
+ stop_grace_period: 45s # Superior ao SHUTDOWN_TIMEOUT da aplicação
125
+ environment:
126
+ - SHUTDOWN_TIMEOUT=30
127
+ - URL_REPOSITORY=http://bff:8080/repository-clickhouse/
128
+ - URL_BFF=http://bff:8080/
129
+ networks:
130
+ - swarm_network
131
+ deploy:
132
+ replicas: 2
133
+ update_config:
134
+ parallelism: 1
135
+ delay: 10s
136
+ order: start-first
137
+ ```
138
+
97
139
  ## Estrutura do Projeto
98
140
 
99
- - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas e Swagger.
141
+ - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas, Swagger e Graceful Shutdown.
100
142
  - `Configs`: Gerencia o carregamento de variáveis de ambiente e a configuração do logger JSON.
101
- - `Interceptor`: Middleware Flask que captura dados de performance e logs de entrada/saída.
143
+ - `GracefulShutdown`: Gerenciador de encerramento suave e sincronização de tarefas/requisições.
144
+ - `Interceptor`: Middleware Flask que captura dados de performance, telemetria e controla requisições ativas.
102
145
  - `HttpRepository`: Facilita requisições HTTP externas com injeção de headers de segurança e rastreio.
103
146
  - `RequestInfo`: Utilitário para gerenciar IDs de correlação (Correlation IDs) entre threads.
104
147
 
@@ -19,3 +19,4 @@ class Config(Enum):
19
19
  API_TOKEN = "API_TOKEN"
20
20
  GITHUB_USER = "GITHUB_USER"
21
21
  GITHUB_PASS = "GITHUB_PASS"
22
+ SHUTDOWN_TIMEOUT = "SHUTDOWN_TIMEOUT"
@@ -11,6 +11,7 @@ from csctracker_py_core.models.emuns.config import Config
11
11
  from csctracker_py_core.repository.http_repository import HttpRepository
12
12
  from csctracker_py_core.repository.remote_repository import RemoteRepository
13
13
  from csctracker_py_core.utils.configs import Configs
14
+ from csctracker_py_core.utils.graceful_shutdown import GracefulShutdown
14
15
  from csctracker_py_core.utils.interceptor import Interceptor
15
16
  from csctracker_py_core.utils.version import Version
16
17
 
@@ -31,6 +32,9 @@ class Starter:
31
32
  self.cors = CORS(self.app)
32
33
  self.app.config["CORS_HEADERS"] = "Content-Type"
33
34
  self.config = Configs(os.getenv("PROFILE", "dev"))
35
+ shutdown_timeout = Configs.get_env_variable(Config.SHUTDOWN_TIMEOUT, default=30)
36
+ self.graceful_shutdown = GracefulShutdown.get_instance(timeout=shutdown_timeout)
37
+ self.graceful_shutdown.register_signals()
34
38
  self.remote_repository = RemoteRepository()
35
39
  self.http_repository = HttpRepository(remote_repository=self.remote_repository)
36
40
  self.interceptor = Interceptor(
@@ -42,6 +46,12 @@ class Starter:
42
46
  default_labels={"application": Version.get_app_name()},
43
47
  )
44
48
 
49
+ def register_shutdown_hook(self, callback):
50
+ self.graceful_shutdown.register_shutdown_hook(callback)
51
+
52
+ def get_graceful_shutdown(self):
53
+ return self.graceful_shutdown
54
+
45
55
  def get_remote_repository(self):
46
56
  return self.remote_repository
47
57
 
@@ -0,0 +1,146 @@
1
+ import logging
2
+ import os
3
+ import signal
4
+ import threading
5
+ import time
6
+ from typing import Callable, List, Optional
7
+
8
+ from csctracker_queue_scheduler.services.scheduler_service import SchedulerService
9
+
10
+
11
+ class GracefulShutdown:
12
+ _instance: Optional["GracefulShutdown"] = None
13
+ _lock = threading.Lock()
14
+
15
+ def __init__(self, timeout: int = 30):
16
+ self.timeout = timeout
17
+ self.is_shutting_down = False
18
+ self.active_requests = 0
19
+ self._condition = threading.Condition(self._lock)
20
+ self._shutdown_hooks: List[Callable] = []
21
+ self.logger = logging.getLogger()
22
+
23
+ @classmethod
24
+ def get_instance(cls, timeout: Optional[int] = None) -> "GracefulShutdown":
25
+ with cls._lock:
26
+ if cls._instance is None:
27
+ cls._instance = cls(timeout=timeout if timeout is not None else 30)
28
+ elif timeout is not None:
29
+ cls._instance.timeout = timeout
30
+ assert cls._instance is not None
31
+ return cls._instance
32
+
33
+ @classmethod
34
+ def reset_instance(cls):
35
+ with cls._lock:
36
+ cls._instance = None
37
+
38
+ def register_signals(self):
39
+ try:
40
+ signal.signal(signal.SIGTERM, self._handle_signal)
41
+ except (ValueError, AttributeError) as e:
42
+ self.logger.warning(f"Could not register SIGTERM handler: {e}")
43
+
44
+ try:
45
+ signal.signal(signal.SIGINT, self._handle_signal)
46
+ except (ValueError, AttributeError) as e:
47
+ self.logger.warning(f"Could not register SIGINT handler: {e}")
48
+
49
+ def start_request(self):
50
+ with self._condition:
51
+ self.active_requests += 1
52
+
53
+ def end_request(self):
54
+ with self._condition:
55
+ self.active_requests = max(0, self.active_requests - 1)
56
+ self._condition.notify_all()
57
+
58
+ def register_shutdown_hook(self, callback: Callable):
59
+ with self._lock:
60
+ self._shutdown_hooks.append(callback)
61
+
62
+ def _handle_signal(self, signum, frame):
63
+ signal_name = "SIGTERM" if signum == signal.SIGTERM else ("SIGINT" if signum == signal.SIGINT else str(signum))
64
+ self.logger.info(f"Signal {signal_name} received. Starting graceful shutdown...")
65
+ with self._lock:
66
+ if self.is_shutting_down:
67
+ return
68
+ self.is_shutting_down = True
69
+
70
+ threading.Thread(target=self._wait_and_exit, args=(True,), daemon=False).start()
71
+
72
+ def wait_for_drain(self, timeout: Optional[int] = None, exit_process: bool = False):
73
+ self._wait_and_exit(exit_process=exit_process, override_timeout=timeout)
74
+
75
+ def _wait_and_exit(self, exit_process: bool = True, override_timeout: Optional[int] = None):
76
+ timeout = override_timeout if override_timeout is not None else self.timeout
77
+ start_time = time.time()
78
+
79
+ # 1. Wait for active HTTP requests to reach 0
80
+ with self._condition:
81
+ while self.active_requests > 0:
82
+ elapsed = time.time() - start_time
83
+ remaining = timeout - elapsed
84
+ if remaining <= 0:
85
+ self.logger.warning(
86
+ f"Timeout reached ({timeout}s) with {self.active_requests} active HTTP requests."
87
+ )
88
+ break
89
+ self._condition.wait(timeout=min(remaining, 0.5))
90
+
91
+ # 2. Wait for SchedulerService queue to be empty and pending tasks to finish
92
+ self._wait_for_scheduler_queue(start_time, timeout)
93
+
94
+ # 3. Execute custom shutdown hooks
95
+ with self._lock:
96
+ hooks = list(self._shutdown_hooks)
97
+
98
+ for hook in hooks:
99
+ try:
100
+ hook()
101
+ except Exception as e:
102
+ self.logger.error(f"Error executing shutdown hook: {e}")
103
+
104
+ self.logger.info("Graceful shutdown completed successfully. Exiting process.")
105
+ if exit_process:
106
+ os._exit(0)
107
+
108
+ def _wait_for_scheduler_queue(self, start_time: float, timeout: int):
109
+ while True:
110
+ elapsed = time.time() - start_time
111
+ if elapsed >= timeout:
112
+ self.logger.warning(
113
+ f"Timeout reached ({timeout}s) waiting for SchedulerService queue."
114
+ )
115
+ break
116
+
117
+ queue_empty = True
118
+ try:
119
+ queue_service = SchedulerService.get_queue_service()
120
+ if queue_service is not None:
121
+ normal_unfinished = getattr(
122
+ getattr(queue_service, "normal_queue", None), "unfinished_tasks", 0
123
+ )
124
+ priority_unfinished = getattr(
125
+ getattr(queue_service, "priority_queue", None), "unfinished_tasks", 0
126
+ )
127
+ normal_empty = (
128
+ queue_service.normal_queue.empty()
129
+ if hasattr(queue_service, "normal_queue")
130
+ else True
131
+ )
132
+ priority_empty = (
133
+ queue_service.priority_queue.empty()
134
+ if hasattr(queue_service, "priority_queue")
135
+ else True
136
+ )
137
+
138
+ if not (normal_empty and priority_empty and normal_unfinished == 0 and priority_unfinished == 0):
139
+ queue_empty = False
140
+ except Exception as e:
141
+ self.logger.debug(f"Error checking SchedulerService: {e}")
142
+
143
+ if queue_empty:
144
+ self.logger.info("SchedulerService queue drained successfully.")
145
+ break
146
+ time.sleep(0.5)
@@ -1,7 +1,6 @@
1
1
  import logging
2
2
  import threading
3
3
  import time
4
- import token
5
4
  from datetime import datetime
6
5
 
7
6
  from csctracker_queue_scheduler.services.scheduler_service import SchedulerService
@@ -10,6 +9,7 @@ from flask import Flask, request, g
10
9
  from csctracker_py_core.models.emuns.config import Config
11
10
  from csctracker_py_core.repository.http_repository import HttpRepository
12
11
  from csctracker_py_core.utils.configs import Configs
12
+ from csctracker_py_core.utils.graceful_shutdown import GracefulShutdown
13
13
  from csctracker_py_core.utils.request_info import RequestInfo
14
14
  from csctracker_py_core.utils.utils import Utils
15
15
  from csctracker_py_core.utils.version import Version
@@ -27,12 +27,17 @@ class Interceptor:
27
27
  def __init(self):
28
28
  @self.app.before_request
29
29
  def start_timer():
30
+ GracefulShutdown.get_instance().start_request()
30
31
  g.start = time.time()
31
32
  correlation_id = RequestInfo.get_correlation_id()
32
33
  g.correlation_id = correlation_id
33
34
  thread = threading.current_thread()
34
35
  thread.correlation_id = correlation_id
35
36
 
37
+ @self.app.teardown_request
38
+ def teardown_request(exception=None):
39
+ GracefulShutdown.get_instance().end_request()
40
+
36
41
  @self.app.after_request
37
42
  def log_request(response):
38
43
  now = time.time()
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: csctracker-py-core
3
- Version: 26.37.2
3
+ Version: 26.37.4
4
4
  Summary: A base library for microservices with Flask, JSON logging, and Prometheus telemetry.
5
5
  Home-page: https://github.com/krlsedu/CscTrackerPyCore
6
6
  Author: Carlos Eduardo
@@ -66,6 +66,7 @@ CscTrackerPyCore é uma biblioteca Python base desenvolvida para padronizar e ac
66
66
  - **Interceptor de Requisições**: Registro detalhado de chamadas HTTP (método, path, status, duração) com opção de persistência remota para auditoria.
67
67
  - **Documentação Automática**: Geração de especificação **Swagger (OpenAPI)** simplificada.
68
68
  - **Processamento em Background**: Integração com `csctracker-queue-scheduler` para execução de tarefas assíncronas e agendadas.
69
+ - **Graceful Shutdown para Docker Swarm**: Encerramento controlado em rolling updates, aguardando término de requisições HTTP e esvaziamento total da fila do scheduler antes do encerramento do processo.
69
70
  - **Repositórios Remotos**: Abstração para comunicação entre serviços via HTTP com tratamento de headers e correlação.
70
71
 
71
72
  ## Requisitos
@@ -107,6 +108,7 @@ A biblioteca é configurada principalmente via variáveis de ambiente, suportand
107
108
  | `LOG_RESPONSE_BODY` | Se `True`, inclui o corpo da resposta nos logs | `False` |
108
109
  | `URL_BFF` | URL base para persistência de logs de requisição | `http://api-gateway/` |
109
110
  | `API_TOKEN` | Token de autorização para chamadas externas | `seu_token_aqui` |
111
+ | `SHUTDOWN_TIMEOUT` | Tempo limite (segundos) para conclusão de requisições e tarefas em background durante o shutdown | `30` |
110
112
  | `DEBUG` | Ativa o modo debug do Flask se definido como `1` | `0` |
111
113
 
112
114
  ## Uso Didático
@@ -144,11 +146,52 @@ Uma vez iniciado o `Starter`, todos os logs do sistema usarão o formato JSON e
144
146
  http_repo = starter.get_http_repository()
145
147
  ```
146
148
 
149
+ ### 4. Graceful Shutdown e Ganchos Customizados
150
+
151
+ Ao receber sinais como `SIGTERM` (pelo Docker Swarm) ou `SIGINT` (Ctrl+C), a aplicação:
152
+ 1. Aguarda a finalização de todas as requisições HTTP ativas.
153
+ 2. Aguarda o esvaziamento completo e processamento da fila do `SchedulerService`.
154
+ 3. Executa ganchos de limpeza customizados registrados via `starter.register_shutdown_hook(...)`.
155
+ 4. Finaliza o processo com segurança respeitando o `SHUTDOWN_TIMEOUT`.
156
+
157
+ ```python
158
+ def cleanup_resources():
159
+ print("Fechando conexões e pools externos...")
160
+
161
+ starter.register_shutdown_hook(cleanup_resources)
162
+ ```
163
+
164
+ ## Implantação no Docker Swarm
165
+
166
+ Para garantir atualizações contínuas (*rolling updates zero-downtime*), configure o `docker-compose.yml` da stack no Swarm utilizando `order: start-first` e defina `stop_grace_period` com um valor superior ao `SHUTDOWN_TIMEOUT`:
167
+
168
+ ```yaml
169
+ version: "3.8"
170
+
171
+ services:
172
+ notification-ai:
173
+ image: krlsedu/csctracker-notification-ai:26.37.002
174
+ stop_grace_period: 45s # Superior ao SHUTDOWN_TIMEOUT da aplicação
175
+ environment:
176
+ - SHUTDOWN_TIMEOUT=30
177
+ - URL_REPOSITORY=http://bff:8080/repository-clickhouse/
178
+ - URL_BFF=http://bff:8080/
179
+ networks:
180
+ - swarm_network
181
+ deploy:
182
+ replicas: 2
183
+ update_config:
184
+ parallelism: 1
185
+ delay: 10s
186
+ order: start-first
187
+ ```
188
+
147
189
  ## Estrutura do Projeto
148
190
 
149
- - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas e Swagger.
191
+ - `Starter`: Orquestrador principal que configura Flask, CORS, Métricas, Swagger e Graceful Shutdown.
150
192
  - `Configs`: Gerencia o carregamento de variáveis de ambiente e a configuração do logger JSON.
151
- - `Interceptor`: Middleware Flask que captura dados de performance e logs de entrada/saída.
193
+ - `GracefulShutdown`: Gerenciador de encerramento suave e sincronização de tarefas/requisições.
194
+ - `Interceptor`: Middleware Flask que captura dados de performance, telemetria e controla requisições ativas.
152
195
  - `HttpRepository`: Facilita requisições HTTP externas com injeção de headers de segurança e rastreio.
153
196
  - `RequestInfo`: Utilitário para gerenciar IDs de correlação (Correlation IDs) entre threads.
154
197
 
@@ -17,7 +17,9 @@ csctracker_py_core/repository/http_repository.py
17
17
  csctracker_py_core/repository/remote_repository.py
18
18
  csctracker_py_core/utils/__init__.py
19
19
  csctracker_py_core/utils/configs.py
20
+ csctracker_py_core/utils/graceful_shutdown.py
20
21
  csctracker_py_core/utils/interceptor.py
21
22
  csctracker_py_core/utils/request_info.py
22
23
  csctracker_py_core/utils/utils.py
23
- csctracker_py_core/utils/version.py
24
+ csctracker_py_core/utils/version.py
25
+ tests/test_graceful_shutdown.py
@@ -0,0 +1,131 @@
1
+ import time
2
+ import unittest
3
+
4
+ from flask import Flask
5
+
6
+ from csctracker_queue_scheduler.services.scheduler_service import SchedulerService
7
+ from csctracker_py_core.repository.http_repository import HttpRepository
8
+ from csctracker_py_core.repository.remote_repository import RemoteRepository
9
+ from csctracker_py_core.starter import Starter
10
+ from csctracker_py_core.utils.graceful_shutdown import GracefulShutdown
11
+ from csctracker_py_core.utils.interceptor import Interceptor
12
+
13
+
14
+ class TestGracefulShutdown(unittest.TestCase):
15
+ def setUp(self):
16
+ GracefulShutdown.reset_instance()
17
+
18
+ def tearDown(self):
19
+ GracefulShutdown.reset_instance()
20
+
21
+ def test_active_requests_tracking(self):
22
+ shutdown = GracefulShutdown.get_instance(timeout=10)
23
+ self.assertEqual(shutdown.active_requests, 0)
24
+
25
+ shutdown.start_request()
26
+ shutdown.start_request()
27
+ self.assertEqual(shutdown.active_requests, 2)
28
+
29
+ shutdown.end_request()
30
+ self.assertEqual(shutdown.active_requests, 1)
31
+
32
+ shutdown.end_request()
33
+ self.assertEqual(shutdown.active_requests, 0)
34
+
35
+ # Ensure counter does not go below 0
36
+ shutdown.end_request()
37
+ self.assertEqual(shutdown.active_requests, 0)
38
+
39
+ def test_interceptor_request_lifecycle(self):
40
+ shutdown = GracefulShutdown.get_instance(timeout=10)
41
+ app = Flask(__name__)
42
+ remote_repo = RemoteRepository()
43
+ http_repo = HttpRepository(remote_repository=remote_repo)
44
+ Interceptor(app, http_repo, save_request=False)
45
+
46
+ @app.route("/ok")
47
+ def ok():
48
+ self.assertEqual(shutdown.active_requests, 1)
49
+ return {"status": "ok"}
50
+
51
+ @app.route("/error")
52
+ def error():
53
+ self.assertEqual(shutdown.active_requests, 1)
54
+ raise RuntimeError("Test simulated error")
55
+
56
+ client = app.test_client()
57
+
58
+ # Test normal request
59
+ resp = client.get("/ok")
60
+ self.assertEqual(resp.status_code, 200)
61
+ self.assertEqual(shutdown.active_requests, 0)
62
+
63
+ # Test error request (teardown_request must still decrement)
64
+ try:
65
+ client.get("/error")
66
+ except RuntimeError:
67
+ pass
68
+ self.assertEqual(shutdown.active_requests, 0)
69
+
70
+ def test_shutdown_hooks_execution(self):
71
+ shutdown = GracefulShutdown.get_instance(timeout=5)
72
+ call_order = []
73
+
74
+ def hook1():
75
+ call_order.append(1)
76
+
77
+ def faulty_hook():
78
+ call_order.append(2)
79
+ raise ValueError("Error in hook")
80
+
81
+ def hook3():
82
+ call_order.append(3)
83
+
84
+ shutdown.register_shutdown_hook(hook1)
85
+ shutdown.register_shutdown_hook(faulty_hook)
86
+ shutdown.register_shutdown_hook(hook3)
87
+
88
+ shutdown.wait_for_drain(timeout=2, exit_process=False)
89
+ self.assertEqual(call_order, [1, 2, 3])
90
+
91
+ def test_timeout_safeguard(self):
92
+ shutdown = GracefulShutdown.get_instance(timeout=1)
93
+ shutdown.start_request() # Stalled request
94
+
95
+ start = time.time()
96
+ shutdown.wait_for_drain(timeout=1, exit_process=False)
97
+ duration = time.time() - start
98
+
99
+ self.assertGreaterEqual(duration, 0.9)
100
+ self.assertLess(duration, 3.0)
101
+
102
+ def test_scheduler_queue_draining(self):
103
+ SchedulerService.init(threads=2)
104
+ shutdown = GracefulShutdown.get_instance(timeout=15)
105
+
106
+ processed = []
107
+
108
+ def sample_job(val):
109
+ time.sleep(0.1)
110
+ processed.append(val)
111
+
112
+ SchedulerService.put_in_queue(sample_job, args={"val": "job1"}, priority=False)
113
+ SchedulerService.put_in_queue(sample_job, args={"val": "job2"}, priority=True)
114
+
115
+ shutdown.wait_for_drain(timeout=15, exit_process=False)
116
+
117
+ self.assertIn("job1", processed)
118
+ self.assertIn("job2", processed)
119
+
120
+ def test_starter_graceful_shutdown_integration(self):
121
+ starter = Starter(save_request=False)
122
+ shutdown = starter.get_graceful_shutdown()
123
+ self.assertIsNotNone(shutdown)
124
+
125
+ hook_called = []
126
+ starter.register_shutdown_hook(lambda: hook_called.append(True))
127
+ self.assertEqual(len(shutdown._shutdown_hooks), 1)
128
+
129
+
130
+ if __name__ == "__main__":
131
+ unittest.main()