health

The library supports two modes of executing health checks:

1. Synchronous Checks (WithCheck): These are executed every time an HTTP request hits the health endpoint. The handler waits for all check functions to complete before returning the aggregated result. This is simple but can increase latency and impact service availability if checks are slow.

2. Asynchronous (Periodic) Checks (WithPeriodicCheck): These execute on a fixed schedule in the background. The HTTP handler reads the most recent result from a local cache, allowing for near-instant responses. This is recommended for expensive or high-latency checks to avoid service disruptions in cloud environments like Kubernetes.

You can mix both types in a single Checker.

To add the health check library to your Go project, use the following command:

go get github.com/alexliesenfeld/health

The health library is designed to be compatible with existing Go health check implementations (e.g., for Redis, Postgres, etc.) instead of requiring you to rewrite them. You can wrap existing check functions or objects into a health.Check struct and register them using health.WithCheck.

Common compatible libraries include:

• github.com/hellofresh/health-go
• github.com/etherlabsio/healthcheck
• github.com/heptiolabs/healthcheck
• github.com/InVisionApp/go-health

// Example: Integrating hellofresh/health-go
import httpCheck "github.com/hellofresh/health-go/v4/checks/http"

health.WithCheck(health.Check{
   Name:    "google",
   Check:   httpCheck.New(httpCheck.Config{
      URL: "https://www.google.com",
   }),
})

The CheckState struct tracks the historical and current status of an individual component check:

• Status: Current AvailabilityStatus.
• LastCheckedAt: Timestamp of the last execution.
• LastSuccessAt: Timestamp of the last successful execution (no error).
• LastFailureAt: Timestamp of the last failed execution.
• FirstCheckStartedAt: When the component was first monitored.
• ContiguousFails: Number of consecutive failures.
• Result: The actual error returned by the last check.

Status transitions to StatusDown are governed by MaxTimeInError and MaxContiguousFails configurations, which prevent flapping by requiring a threshold of failures or a duration of error before declaring a component 'down'.

Middleware allows you to intercept the health check process. A Middleware is a factory function that takes a MiddlewareFunc (the next step in the chain) and returns a new MiddlewareFunc.

Crucial Requirement: Every middleware must call the next function passed to it. If next is not called, the underlying Checker.Check will never be executed.

// Example of a middleware that logs the request
func LoggingMiddleware(next health.MiddlewareFunc) health.MiddlewareFunc {
	return func(r *http.Request) health.CheckerResult {
		fmt.Printf("Health check requested: %s\n", r.URL.Path)
		return next(r)
	}
}

// Usage
handler := health.NewHandler(myChecker, health.WithMiddleware(LoggingMiddleware))

To prevent excessive load on dependencies and mitigate DoS attacks, the library caches health results.

• The default TTL is 1 second.
• Use health.WithCacheDuration(duration) to customize the TTL.
• Use health.WithDisabledCache() to disable caching entirely.

The library uses two main structures to report health:

1. CheckerResult: The top-level response from Checker.Check(). It contains:

   • Status: The aggregated AvailabilityStatus of the entire system.
   • Details: A map of CheckResult objects, keyed by component name.
   • Info: A map of additional metadata.

2. CheckResult: The status of an individual component. It contains:

   • Status: The AvailabilityStatus of that specific component.
   • Timestamp: When the check was last executed.
   • Error: The error returned by the check (if any).

Note: CheckResult implements custom JSON marshalling to ensure the error interface is correctly serialized as a string.

There are two ways to add checks to a Checker depending on your performance and frequency requirements:

1. On-demand checks (WithCheck / WithChecks): These checks are executed every time Checker.Check is called (e.g., on every incoming HTTP request). Use this for lightweight checks.
2. Periodic checks (WithPeriodicCheck): These checks run on a fixed schedule in the background. The Checker always returns the last successful result. Use this for expensive or long-running checks to avoid blocking HTTP requests.

// On-demand check
checker := health.NewChecker(health.WithCheck(myCheck))

// Periodic check (runs every 30s, starts after 5s delay)
checker := health.NewChecker(health.WithPeriodicCheck(30*time.Second, 5*time.Second, myCheck))

To use InVisionApp/go-health, wrap the checker's .Status() method in a closure that returns the error.

import "github.com/InVisionApp/go-health/checkers"

// ... setup check ...

health.WithCheck(health.Check{
    Name: "google",
    Check: func(_ context.Context) error {
        _, err := check.Status() 
        return err
    },
})