Health Checks

S-Auth provides health check endpoints for monitoring system availability and diagnosing issues.

Endpoints

Simple Health Check

GET /health

A lightweight endpoint for uptime monitors.

Response:

{
  "status": "ok"
}

Use Cases:

• Uptime monitoring (Better Stack, Pingdom, etc.)
• Load balancer health probes
• Quick availability checks

Characteristics:

• Always responds quickly
• No database dependency
• Returns 200 if the worker is running

---

Detailed Health Check

GET /health/detailed

A comprehensive endpoint that checks all system dependencies.

Response (Healthy):

{
  "status": "healthy",
  "service": "s-auth-oauth-provider",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "total_latency_ms": 15,
  "checks": {
    "database": {
      "status": "ok",
      "latency_ms": 12
    }
  }
}

Response (Degraded):

{
  "status": "degraded",
  "service": "s-auth-oauth-provider",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "total_latency_ms": 5023,
  "checks": {
    "database": {
      "status": "error",
      "error": "Connection timeout"
    }
  }
}

HTTP Status Codes:

• 200 - All checks passed
• 503 - One or more checks failed

Use Cases:

• Detailed monitoring dashboards
• Troubleshooting connectivity issues
• CI/CD deployment verification

---

Better Stack Configuration

Creating a Monitor

1. Go to Better Stack Uptime
2. Click Create Monitor
3. Configure:

Setting	Value
Monitor Type	HTTP(s)
URL	https://auth.sebbyk.net/health
Request Timeout	30 seconds
Check Frequency	Every 3 minutes
Verify SSL	Yes

4. Configure alerts (email, Slack, etc.)
5. Save

Choosing the Right Endpoint

Scenario	Endpoint	Why
Basic uptime monitoring	/health	Fast, lightweight
Comprehensive monitoring	/health/detailed	Checks all dependencies
Status page	/health/detailed	Shows system status

---

Status Page Integration

Better Stack Status Page

1. Create a status page in Better Stack
2. Add your health monitor
3. Configure components:

S-Auth OAuth Provider
├── Authentication Service (/health)
└── Database Connectivity (/health/detailed)

4. Set your custom domain (e.g., status.sebbyk.net)

Status Mapping

Response	Status Page Display
"status": "healthy"	Operational
"status": "degraded"	Partial Outage
No response	Major Outage

---

Interpreting Results

Database Check

The database check runs:

SELECT 1

Status	Meaning
ok	D1 database is responsive
error	Database unreachable or query failed

Latency Guidelines:

• < 50ms: Excellent
• 50-200ms: Normal
• 200-500ms: Slow (investigate)

• 500ms: Performance issue

Common Issues

High Database Latency

Symptoms:

• latency_ms consistently > 200ms
• Intermittent degraded status

Causes:

• D1 database under heavy load
• Network issues in Cloudflare region
• Query complexity (not applicable for health check)

Solutions:

• Check Cloudflare status page
• Review recent code changes
• Contact Cloudflare support if persistent

Database Connection Errors

Symptoms:

• "status": "error" on database check
• Error messages like "Connection refused"

Causes:

• D1 database not properly bound
• Cloudflare Workers environment issue
• Database migrations needed

Solutions:

• Verify wrangler.toml configuration
• Run wrangler d1 list to check database status
• Review Cloudflare Workers logs

---

Alerting Best Practices

Alert Thresholds

Condition	Alert Level
1 failed check	Warning
3 consecutive failures	Critical
Status degraded	Warning
Status unhealthy	Critical

Alert Channels

Recommended setup:

• Email - All alerts
• Slack - Critical alerts
• PagerDuty/Opsgenie - On-call rotation

Runbook Links

Include links to troubleshooting docs in your alerts:

• Health check docs (this page)
• Common issues and solutions
• Escalation contacts

---

Local Development

Test health checks locally:

# Start the dev server
cd oauth-provider
npm run dev

# Test simple health check
curl http://localhost:8787/health

# Test detailed health check
curl http://localhost:8787/health/detailed

Expected output:

{
  "status": "healthy",
  "service": "s-auth-oauth-provider",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "total_latency_ms": 5,
  "checks": {
    "database": {
      "status": "ok",
      "latency_ms": 3
    }
  }
}