Health-Check Plugin

The Health-Check plugin provides HTTP endpoints for monitoring server health, readiness, and liveness. It enables external monitoring systems, load balancers, and orchestration platforms to check the server's operational status.

Overview

Modern infrastructure requires applications to expose their health status for automated monitoring and orchestration. The health-check plugin implements standard health check patterns with three types of checks: comprehensive health, liveness (is the server running?), and readiness (is the server ready to handle requests?). These endpoints are essential for Kubernetes deployments, load balancer health checks, and monitoring systems.

Key Features

• Multiple check types: Health, readiness, and liveness endpoints
• Configurable endpoints: Customize health check URLs
• Detailed responses: JSON responses with check details
• Resource checks: Verify disk space and document root access
• No-cache headers: Ensures fresh health status
• Graceful degradation: Distinguishes between healthy, degraded, and unhealthy states

Configuration

The health-check plugin is configured as part of the plugin pipeline in your host configuration:

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/health-check.so</span>
    <meta itemprop="health_endpoint" content="/health">
    <meta itemprop="ready_endpoint" content="/ready">
    <meta itemprop="live_endpoint" content="/live">
</li>

Configuration Parameters

Health Check Types

Liveness Check (/live)

Indicates if the server process is running and able to respond to requests:

• Always returns 200 OK if the server is running
• Minimal check - just proves the server can respond
• Used by orchestrators to restart unhealthy containers

curl http://localhost:3000/live

{
  "status": "healthy",
  "checks": ["Server is running"],
  "timestamp": 1728569432
}

Readiness Check (/ready)

Indicates if the server is ready to handle requests:

• Checks document root accessibility
• Verifies disk space (if enabled)
• Returns 503 if not ready
• Used by load balancers to route traffic

curl http://localhost:3000/ready

{
  "status": "healthy",
  "checks": [
    "Document root accessible: ./public",
    "Disk space OK: 1024 MB available"
  ],
  "timestamp": 1728569432
}

Health Check (/health)

Comprehensive health status combining liveness and readiness:

• Performs all checks
• Provides detailed status information
• Can return healthy, degraded, or unhealthy status
• Used by monitoring systems

curl http://localhost:3000/health

{
  "status": "healthy",
  "checks": [
    "Server is running",
    "Document root accessible: ./public",
    "Disk space OK: 1024 MB available",
    "Timestamp: 1728569432",
    "Server: rusty-beam"
  ],
  "timestamp": 1728569432
}

Status Codes and States

Plugin Pipeline Placement

Typical pipeline order:

1. health-check.so    → Health endpoints ✓
2. basic-auth.so      → Authentication (skips health checks)
3. authorization.so   → Authorization
4. file-handler.so    → Content serving

Examples

Basic Configuration

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/health-check.so</span>
</li>

Custom Endpoints

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/health-check.so</span>
    <meta itemprop="health_endpoint" content="/_health">
    <meta itemprop="ready_endpoint" content="/_ready">
    <meta itemprop="live_endpoint" content="/_live">
    <meta itemprop="min_disk_space_mb" content="500">
</li>

Minimal Responses

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/health-check.so</span>
    <meta itemprop="detailed_checks" content="false">
    <meta itemprop="check_disk_space" content="false">
</li>

Integration Examples

Kubernetes Configuration

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: rusty-beam
    image: rusty-beam:latest
    livenessProbe:
      httpGet:
        path: /live
        port: 3000
      initialDelaySeconds: 10
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /ready
        port: 3000
      initialDelaySeconds: 5
      periodSeconds: 5

Docker Compose Health Check

version: '3.8'
services:
  rusty-beam:
    image: rusty-beam:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Load Balancer Configuration (nginx)

upstream backend {
    server backend1.example.com:3000 max_fails=3 fail_timeout=30s;
    server backend2.example.com:3000 max_fails=3 fail_timeout=30s;
}

location / {
    proxy_pass http://backend;
}

location /health-check {
    access_log off;
    proxy_pass http://backend/ready;
    proxy_read_timeout 5s;
}

Monitoring with Prometheus

# prometheus.yml
scrape_configs:
  - job_name: 'rusty-beam'
    metrics_path: '/health'
    static_configs:
      - targets: ['localhost:3000']
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        replacement: 'rusty-beam-1'

Shell Monitoring Script

#!/bin/bash
# health-monitor.sh

HEALTH_URL="http://localhost:3000/health"
ALERT_EMAIL="ops@example.com"

check_health() {
    response=$(curl -s -w "\n%{http_code}" "$HEALTH_URL")
    http_code=$(echo "$response" | tail -1)
    body=$(echo "$response" | head -n -1)
    
    if [ "$http_code" != "200" ]; then
        echo "Health check failed with HTTP $http_code"
        echo "$body" | mail -s "Rusty Beam Health Check Failed" "$ALERT_EMAIL"
        return 1
    fi
    
    status=$(echo "$body" | jq -r '.status')
    if [ "$status" = "degraded" ]; then
        echo "Server is degraded"
        echo "$body" | mail -s "Rusty Beam Degraded" "$ALERT_EMAIL"
    fi
    
    return 0
}

# Run check every minute
while true; do
    check_health
    sleep 60
done

Best Practices

• Separate endpoints: Use different endpoints for different purposes
• Fast responses: Health checks should respond quickly (<1s)
• No authentication: Health endpoints should be publicly accessible
• Conservative readiness: Only mark ready when truly ready to serve
• Graceful shutdown: Mark as not ready before stopping the server
• Resource limits: Set appropriate disk space thresholds

Security Considerations

• Information disclosure: Detailed checks may reveal system information
• DoS protection: Consider rate limiting health endpoints
• Network isolation: Restrict health checks to internal networks when possible
• Path obfuscation: Use non-obvious paths for health endpoints if needed

Troubleshooting

Common Issues

Debug Logging

Run the server with -v flag to see health check details:

./rusty-beam -v config.html

Response Headers

Health check responses include these headers:

• Content-Type: application/json
• Cache-Control: no-cache, no-store, must-revalidate

Future Enhancements

See Also

• Plugin Schema - Plugin configuration format
• Access-Log Plugin - Log health check requests
• Kubernetes Health Checks
• Health Check Response Format for HTTP APIs