Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(health): describe the draining 503 on the readiness probe

Yudhi Armyndharisb40ee7df66c3
diff --git a/src/modules/health/health.controller.spec.ts b/src/modules/health/health.controller.spec.ts
index 0038d550d..311fc2e41 100644
--- a/src/modules/health/health.controller.spec.ts
+++ b/src/modules/health/health.controller.spec.ts
@@ -4,6 +4,7 @@ import { ServiceUnavailableException, UnauthorizedException } from '@nestjs/comm
import { ConfigService } from '@nestjs/config';
import { Request } from 'express';
import { HealthController } from './health.controller';
+import { ReadinessResponseDto } from './dto/health-response.dto';
import { ShutdownService } from '../../common/services/shutdown.service';
import { AuthService } from '../auth/auth.service';
import { AuditService } from '../audit/audit.service';
@@ -269,5 +270,16 @@ describe('HealthController', () => {
expect(mainQuery).not.toHaveBeenCalled();
expect(dataQuery).not.toHaveBeenCalled();
});
+
+ // The draining 503 answers while every database is up, so the contract must not describe the
+ // status as a dependency outage only.
+ it('documents both 503 causes with the readiness body shape', () => {
+ const responses = Reflect.getMetadata(
+ 'swagger/apiResponse',
+ Object.getOwnPropertyDescriptor(HealthController.prototype, 'readiness')?.value as object,
+ ) as Record<string, { description: string; type?: unknown }>;
+ expect(responses['503'].description).toContain('draining');
+ expect(responses['503'].type).toBe(ReadinessResponseDto);
+ });
});
});
diff --git a/src/modules/health/health.controller.ts b/src/modules/health/health.controller.ts
index 9f04ce309..ed6fe96c0 100644
--- a/src/modules/health/health.controller.ts
+++ b/src/modules/health/health.controller.ts
@@ -121,7 +121,12 @@ export class HealthController {
@Get('ready')
@ApiOperation({ summary: 'Readiness probe — verifies the auth/audit + data databases respond' })
@ApiResponse({ status: 200, description: 'Application is ready to accept traffic', type: ReadinessResponseDto })
- @ApiResponse({ status: 503, description: 'A required dependency is down' })
+ @ApiResponse({
+ status: 503,
+ description:
+ 'A required dependency is down, or the node is draining for shutdown (details.shutdown.status = draining)',
+ type: ReadinessResponseDto,
+ })
async readiness(): Promise<HealthCheckResult> {
// While draining (shutdown started), report 503 so the LB/orchestrator stops
// routing new traffic before teardown — even if the DBs are still up.