Health Checks

The router package provides helpers for registering common health check endpoints.

Health checks are useful for:

• container orchestration
• load balancers
• deployment probes
• service monitoring
• graceful startup and shutdown flows

There are two common types of health checks:

• Liveness: tells whether the process is running
• Readiness: tells whether the application is ready to receive traffic

Liveness

A liveness endpoint usually returns 200 OK when the process is alive.

r.Liveness("/healthz", func(w http.ResponseWriter, req *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))
})

Example request:

curl http://localhost:8080/healthz

Expected response:

OK

Readiness

A readiness endpoint should return 200 OK only when the application is ready to serve requests.

r.Readiness("/readyz", func(w http.ResponseWriter, req *http.Request) {
	if r.IsReady() {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("READY"))
	} else {
		w.WriteHeader(http.StatusServiceUnavailable)
		w.Write([]byte("NOT_READY"))
	}
})

Example request:

curl http://localhost:8080/readyz

Expected response when ready:

READY

Expected response when not ready:

NOT_READY

Readiness State

The router keeps an internal readiness state.

By default, a new router starts in the ready state.

r := router.New()

You can update the readiness state manually:

r.SetReady(false)

This is useful during startup, shutdown, migrations, dependency checks, or when the service should temporarily stop receiving traffic.

Example:

r.SetReady(false)

// initialize database connections
// warm up cache
// load configuration

r.SetReady(true)

Default Paths

If an empty path is provided, the router uses default health check paths:

r.Liveness("", handler)  // /healthz
r.Readiness("", handler) // /readyz

Notes

Health check handlers are regular net/http handlers.

They are registered through the router’s mounting system, so they can be used alongside normal routes, middleware, static files, and mounted handlers.