1---
2title: Implement Graceful Shutdown
3impact: MEDIUM-HIGH
4impactDescription: Proper shutdown handling ensures zero-downtime deployments
5tags: devops, graceful-shutdown, lifecycle, kubernetes
6---
7 
8## Implement Graceful Shutdown
9 
10Handle SIGTERM and SIGINT signals to gracefully shutdown your NestJS application. Stop accepting new requests, wait for in-flight requests to complete, close database connections, and clean up resources. This prevents data loss and connection errors during deployments.
11 
12**Incorrect (ignoring shutdown signals):**
13 
14```typescript
15// Ignore shutdown signals
16async function bootstrap() {
17  const app = await NestFactory.create(AppModule);
18  await app.listen(3000);
19  // App crashes immediately on SIGTERM
20  // In-flight requests fail
21  // Database connections are abruptly closed
22}
23 
24// Long-running tasks without cancellation
25@Injectable()
26export class ProcessingService {
27  async processLargeFile(file: File): Promise<void> {
28    // No way to interrupt this during shutdown
29    for (let i = 0; i < file.chunks.length; i++) {
30      await this.processChunk(file.chunks[i]);
31      // May run for minutes, blocking shutdown
32    }
33  }
34}
35```
36 
37**Correct (enable shutdown hooks and handle cleanup):**
38 
39```typescript
40// Enable shutdown hooks in main.ts
41async function bootstrap() {
42  const app = await NestFactory.create(AppModule);
43 
44  // Enable shutdown hooks
45  app.enableShutdownHooks();
46 
47  // Optional: Add timeout for forced shutdown
48  const server = await app.listen(3000);
49  server.setTimeout(30000); // 30 second timeout
50 
51  // Handle graceful shutdown
52  const signals = ['SIGTERM', 'SIGINT'];
53  signals.forEach((signal) => {
54    process.on(signal, async () => {
55      console.log(`Received ${signal}, starting graceful shutdown...`);
56 
57      // Stop accepting new connections
58      server.close(async () => {
59        console.log('HTTP server closed');
60        await app.close();
61        process.exit(0);
62      });
63 
64      // Force exit after timeout
65      setTimeout(() => {
66        console.error('Forced shutdown after timeout');
67        process.exit(1);
68      }, 30000);
69    });
70  });
71}
72 
73// Lifecycle hooks for cleanup
74@Injectable()
75export class DatabaseService implements OnApplicationShutdown {
76  private readonly connections: Connection[] = [];
77 
78  async onApplicationShutdown(signal?: string): Promise<void> {
79    console.log(`Database service shutting down on ${signal}`);
80 
81    // Close all connections gracefully
82    await Promise.all(
83      this.connections.map((conn) => conn.close()),
84    );
85 
86    console.log('All database connections closed');
87  }
88}
89 
90// Queue processor with graceful shutdown
91@Injectable()
92export class QueueService implements OnApplicationShutdown, OnModuleDestroy {
93  private isShuttingDown = false;
94 
95  onModuleDestroy(): void {
96    this.isShuttingDown = true;
97  }
98 
99  async onApplicationShutdown(): Promise<void> {
100    // Wait for current jobs to complete
101    await this.queue.close();
102  }
103 
104  async processJob(job: Job): Promise<void> {
105    if (this.isShuttingDown) {
106      throw new Error('Service is shutting down');
107    }
108    await this.doWork(job);
109  }
110}
111 
112// WebSocket gateway cleanup
113@WebSocketGateway()
114export class EventsGateway implements OnApplicationShutdown {
115  @WebSocketServer()
116  server: Server;
117 
118  async onApplicationShutdown(): Promise<void> {
119    // Notify all connected clients
120    this.server.emit('shutdown', { message: 'Server is shutting down' });
121 
122    // Close all connections
123    this.server.disconnectSockets();
124  }
125}
126 
127// Health check integration
128@Injectable()
129export class ShutdownService {
130  private isShuttingDown = false;
131 
132  startShutdown(): void {
133    this.isShuttingDown = true;
134  }
135 
136  isShutdown(): boolean {
137    return this.isShuttingDown;
138  }
139}
140 
141@Controller('health')
142export class HealthController {
143  constructor(private shutdownService: ShutdownService) {}
144 
145  @Get('ready')
146  @HealthCheck()
147  readiness(): Promise<HealthCheckResult> {
148    // Return 503 during shutdown - k8s stops sending traffic
149    if (this.shutdownService.isShutdown()) {
150      throw new ServiceUnavailableException('Shutting down');
151    }
152 
153    return this.health.check([
154      () => this.db.pingCheck('database'),
155    ]);
156  }
157}
158 
159// Integrate with shutdown
160@Injectable()
161export class AppShutdownService implements OnApplicationShutdown {
162  constructor(private shutdownService: ShutdownService) {}
163 
164  async onApplicationShutdown(): Promise<void> {
165    // Mark as unhealthy first
166    this.shutdownService.startShutdown();
167 
168    // Wait for k8s to update endpoints
169    await this.sleep(5000);
170 
171    // Then proceed with cleanup
172  }
173}
174 
175// Request tracking for in-flight requests
176@Injectable()
177export class RequestTracker implements NestMiddleware, OnApplicationShutdown {
178  private activeRequests = 0;
179  private isShuttingDown = false;
180  private shutdownPromise: Promise<void> | null = null;
181  private resolveShutdown: (() => void) | null = null;
182 
183  use(req: Request, res: Response, next: NextFunction): void {
184    if (this.isShuttingDown) {
185      res.status(503).send('Service Unavailable');
186      return;
187    }
188 
189    this.activeRequests++;
190 
191    res.on('finish', () => {
192      this.activeRequests--;
193      if (this.isShuttingDown && this.activeRequests === 0 && this.resolveShutdown) {
194        this.resolveShutdown();
195      }
196    });
197 
198    next();
199  }
200 
201  async onApplicationShutdown(): Promise<void> {
202    this.isShuttingDown = true;
203 
204    if (this.activeRequests > 0) {
205      console.log(`Waiting for ${this.activeRequests} requests to complete`);
206      this.shutdownPromise = new Promise((resolve) => {
207        this.resolveShutdown = resolve;
208      });
209 
210      // Wait with timeout
211      await Promise.race([
212        this.shutdownPromise,
213        new Promise((resolve) => setTimeout(resolve, 30000)),
214      ]);
215    }
216 
217    console.log('All requests completed');
218  }
219}
220```
221 
222Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
223