Health

The health package provides HTTP endpoints for monitoring application status. It exposes standard liveness and readiness probe URLs with dependency checks against the database and cache. The endpoints work with any orchestrator, load balancer, or uptime monitor that polls HTTP — load balancers expecting a 200/5xx signal, uptime services like Pingdom or UptimeRobot, and the probe-style interfaces used by Kubernetes, Nomad, or container platforms that honor the same convention.

Import


import "github.com/gofastadev/gofasta/pkg/health"

Key Types

Controller


type Controller struct {
    DB    *gorm.DB
    Cache cache.CacheService
}

Key Functions

Function	Signature	Description
`NewController`	`func NewController(db gorm.DB, cacheService cache.CacheService) Controller`	Creates a new health controller; cache can be nil
`Check`	`func (h Controller) Check(w http.ResponseWriter, r http.Request) error`	Basic liveness check (`GET /health`)
`Live`	`func (h Controller) Live(w http.ResponseWriter, r http.Request) error`	Liveness probe (`GET /health/live`)
`Ready`	`func (h Controller) Ready(w http.ResponseWriter, r http.Request) error`	Readiness probe with dependency checks (`GET /health/ready`)

Endpoints

Path	Method	Handler	Description
`/health`	GET	`Check`	Basic liveness — returns `{"status": "up"}`
`/health/live`	GET	`Live`	Liveness probe — process is alive
`/health/ready`	GET	`Ready`	Readiness probe — checks database and cache dependencies

Usage

Setting Up Health Checks


healthController := health.NewController(db, cacheService)
 
mux.HandleFunc("GET /health", healthController.Check)
mux.HandleFunc("GET /health/live", healthController.Live)
mux.HandleFunc("GET /health/ready", healthController.Ready)

If you do not use a cache, pass nil:


healthController := health.NewController(db, nil)

Response Format

GET /health and GET /health/live return:


{
  "status": "up"
}

GET /health/ready returns detailed dependency status:


{
  "status": "up",
  "uptime": "72h30m15s",
  "checks": [
    {
      "name": "database",
      "status": "up",
      "duration": "2.1ms"
    },
    {
      "name": "cache",
      "status": "up",
      "duration": "1.3ms"
    }
  ]
}

When a dependency is down, the endpoint returns HTTP 503:


{
  "status": "down",
  "uptime": "72h30m15s",
  "checks": [
    {
      "name": "database",
      "status": "up",
      "duration": "2.1ms"
    },
    {
      "name": "cache",
      "status": "down",
      "error": "connection refused",
      "duration": "5000ms"
    }
  ]
}

Built-in Checks

The readiness endpoint automatically checks:

Database — Pings the database using the underlying sql.DB connection
Cache (Redis) — Pings the cache service (if configured)

Probe Endpoint Reference

Use these endpoints with your load balancer, uptime monitor, or orchestrator. The scheme below is the one most platforms use to distinguish “is the process running” (liveness) from “can this instance safely take traffic” (readiness):

GET /health/live — returns 200 when the process is running. Used as a restart signal; should almost always be 200 unless the process itself is dead.
GET /health/ready — returns 200 when the process can serve traffic (database and cache reachable). Returns 503 when dependencies are unavailable; a load balancer pulling this instance out of rotation temporarily will restore it when the next poll succeeds.

Health poll guidance:

Liveness — poll every 10–30 s with a short timeout (≤5 s). A failing liveness probe should typically trigger a restart.
Readiness — poll every 5–10 s. A failing readiness probe should remove the instance from traffic but not restart it.

Config — Database and cache configuration for checks
Observability — Metrics complement health checks
Resilience — Circuit breaker states reflected in health