From 0f7e24f2918af0a8cb53d80c7f32833f6a33b839 Mon Sep 17 00:00:00 2001
From: syntaxsuuvam-spec <syntaxsuuvam-spec@users.noreply.github.com>
Date: Sun, 11 Oct 2026 05:24:50 +0545
Subject: [PATCH 1/2] feat(health): define explicit ComponentStatus and
 HealthStatus enums with OpenAPI metadata

---
 src/health/dto/health-response.dto.ts | 34 +++++++++++++++++++++------
 1 file changed, 27 insertions(+), 7 deletions(-)

diff --git a/src/health/dto/health-response.dto.ts b/src/health/dto/health-response.dto.ts
index fe7fdb3..981470c 100644
--- a/src/health/dto/health-response.dto.ts
+++ b/src/health/dto/health-response.dto.ts
@@ -1,8 +1,26 @@
 import { ApiProperty } from "@nestjs/swagger";
 
+export enum ComponentStatus {
+  UP = "up",
+  DOWN = "down",
+  DEGRADED = "degraded",
+  UNKNOWN = "unknown",
+}
+
+export enum HealthStatus {
+  OK = "ok",
+  DEGRADED = "degraded",
+  ERROR = "error",
+}
+
 export class ComponentStatusDto {
-  @ApiProperty({ enum: ["up", "down"], example: "up" })
-  status: "up" | "down";
+  @ApiProperty({
+    enum: ComponentStatus,
+    enumName: "ComponentStatus",
+    example: ComponentStatus.UP,
+    description: "Component availability status: up, down, degraded, or unknown",
+  })
+  status: ComponentStatus | "up" | "down" | "degraded" | "unknown";
 
   @ApiProperty({
     required: false,
@@ -17,14 +35,15 @@ export class ComponentStatusDto {
 
 export class HealthResponseDto {
   @ApiProperty({
-    enum: ["ok", "degraded", "error"],
-    example: "ok",
+    enum: HealthStatus,
+    enumName: "HealthStatus",
+    example: HealthStatus.OK,
     description:
       "ok = all components up; degraded = some up; error = all critical components down",
   })
-  status: "ok" | "degraded" | "error";
+  status: HealthStatus | "ok" | "degraded" | "error";
 
-  @ApiProperty({ example: "2024-01-01T00:00:00.000Z" })
+  @ApiProperty({ example: "2024-01-01T00:00:00.000Z", description: "ISO 8601 evaluation timestamp" })
   timestamp: string;
 
   @ApiProperty({ example: 123.456, description: "Process uptime in seconds" })
@@ -37,6 +56,7 @@ export class HealthResponseDto {
       database: { status: "up", responseTime: 5 },
       redis: { status: "up", responseTime: 2 },
     },
+    description: "Map of component health details keyed by subsystem identifier",
   })
   components: Record<string, ComponentStatusDto>;
-}
+}
\ No newline at end of file

From b32ac150d6687b334b0ed690c0066125010392b7 Mon Sep 17 00:00:00 2001
From: syntaxsuuvam-spec <syntaxsuuvam-spec@users.noreply.github.com>
Date: Sun, 11 Oct 2026 05:25:50 +0545
Subject: [PATCH 2/2] docs(probes): document ComponentStatus and HealthStatus
 enum contracts and HTTP status mappings

---
 docs/kubernetes-health-probes.md | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/kubernetes-health-probes.md b/docs/kubernetes-health-probes.md
index 171e7ef..2ef60ea 100644
--- a/docs/kubernetes-health-probes.md
+++ b/docs/kubernetes-health-probes.md
@@ -29,11 +29,20 @@ All endpoints are public (no authentication required) and excluded from rate lim
 
 ### Status values
 
-| Value | Meaning |
-|---|---|
-| `ok` | All components healthy |
-| `degraded` | Some non-critical components down (readiness only) |
-| `error` | One or more critical components down — returns HTTP 503 |
+| Enum (`HealthStatus`) | Value | Meaning | HTTP Status Mapping |
+|---|---|---|---|
+| `HealthStatus.OK` | `ok` | All components healthy | `200 OK` |
+| `HealthStatus.DEGRADED` | `degraded` | Some non-critical components down (readiness only) | `200 OK` |
+| `HealthStatus.ERROR` | `error` | One or more critical components down | `503 Service Unavailable` |
+
+### Component status values
+
+| Enum (`ComponentStatus`) | Value | Meaning |
+|---|---|---|
+| `ComponentStatus.UP` | `up` | Subsystem responding within timeout threshold |
+| `ComponentStatus.DOWN` | `down` | Subsystem unreachable or throwing error |
+| `ComponentStatus.DEGRADED` | `degraded` | Subsystem responding with high latency or partial capacity |
+| `ComponentStatus.UNKNOWN` | `unknown` | Status evaluation skipped or unconfigured |
 
 ## Kubernetes probe configuration