Health Checks

🏥 Health Checks

BOUNDLY v0.9.0 includes a comprehensive health check system for monitoring and orchestration.

---

📍 Location

Infrastructure\FrameworkCore\Services\Health\
Infrastructure\FrameworkCore\Http\Controllers\HealthController.php

---

🚀 Quick Start

Once enabled, health check endpoints are automatically available:

# Simple health check
GET /api/health

# Detailed health check
GET /api/health?detailed=true

# Kubernetes-style endpoints
GET /api/health/liveness
GET /api/health/readiness

---

Endpoints

GET /api/health

Simple health check returning overall status.

Response (200 - Healthy):

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-03-24T12:00:00Z"
  }
}

Response (503 - Unhealthy):

{
  "success": false,
  "error": {
    "code": "ERR_SERVICE_UNAVAILABLE",
    "message": "Service is unhealthy",
    "details": {
      "status": "unhealthy"
    }
  }
}

---

GET /api/health?detailed=true

Full health check with all service statuses.

Response:

{
  "status": "healthy",
  "timestamp": "2026-03-24T12:00:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "Connection successful",
      "duration_ms": 5.2
    },
    "cache": {
      "status": "healthy",
      "message": "OK",
      "duration_ms": 1.1
    },
    "queue": {
      "status": "healthy",
      "message": "Queue worker running",
      "duration_ms": 0.5
    },
    "storage": {
      "status": "healthy",
      "message": "Storage accessible",
      "duration_ms": 2.3
    }
  }
}

---

GET /api/health/liveness

Kubernetes-style liveness probe. Returns 200 if the application is running.

{
  "success": true,
  "data": {
    "status": "alive",
    "timestamp": "2026-03-24T12:00:00Z"
  }
}

---

GET /api/health/readiness

Kubernetes-style readiness probe. Returns 200 only if critical services are available.

{
  "success": true,
  "data": {
    "status": "ready",
    "timestamp": "2026-03-24T12:00:00Z"
  }
}

---

⚙️ Configuration

// config/boundly.php
'health' => [
    'enabled' => true,
    'timeout' => 5,
    'services' => [
        'database' => true,
        'cache' => true,
        'queue' => true,
        'storage' => true,
    ],
    'custom' => [],
],

Key	Default	Description
enabled	true	Enable/disable health checks
timeout	5	Timeout per check in seconds
services.*	true	Enable/disable individual checks

---

🔧 Custom Health Checks

Create your own health check by implementing HealthCheckInterface:

use Infrastructure\FrameworkCore\Contracts\Health\HealthCheckInterface;
use Infrastructure\FrameworkCore\Contracts\Health\HealthCheckResult;

class ExternalApiHealthCheck implements HealthCheckInterface
{
    public function name(): string
    {
        return 'external_api';
    }

    public function check(): HealthCheckResult
    {
        try {
            $response = Http::timeout(3)->get('https://api.example.com/health');
            
            if ($response->successful()) {
                return HealthCheckResult::healthy('External API reachable', null, 45.2);
            }
            
            return HealthCheckResult::unhealthy('External API returned: ' . $response->status());
        } catch (\Exception $e) {
            return HealthCheckResult::unhealthy('External API unreachable: ' . $e->getMessage());
        }
    }

    public function severity(): string
    {
        return 'critical'; // or 'warning'
    }
}

Register in config:

'health' => [
    'custom' => [
        \App\HealthChecks\ExternalApiHealthCheck::class,
    ],
],

---

📊 Health Check Severity

Severity	Behavior
critical	Check failure affects readiness probe
warning	Check failure is logged but doesn't affect readiness

---

🔌 Services Checked

Service	Description
Database	Verifies MySQL/PostgreSQL/SQLite connectivity
Cache	Verifies Redis/file cache accessibility
Queue	Verifies queue worker is running
Storage	Verifies storage disk is writable

---

Next Step: Logging 📝