TwiN / health

Simple Go health handler

health

Health is a library used for creating a very simple health endpoint.

While implementing a health endpoint is very simple, I've grown tired of implementing it over and over again.

Installation

go get -u github.com/TwiN/health

Usage

To retrieve the handler, you must use health.Handler() and are expected to pass it to the router like so:

router := http.NewServeMux()
router.Handle("/health", health.Handler())
server := &http.Server{
    Addr:    ":8080",
    Handler: router,
}

By default, the handler will return UP when the status is up, and DOWN when the status is down. If you prefer using JSON, however, you may initialize the health handler like so:

router.Handle("/health", health.Handler().WithJSON(true))

The above will cause the response body to become {"status":"UP"} and {"status":"DOWN"} for both status respectively, unless there is a reason, in which case a reason set to because would return {"status":"UP", "reason":"because"} and {"status":"DOWN", "reason":"because"} respectively.

To set the health status to DOWN with a reason:

health.SetUnhealthy("<enter reason here>")

The string passed will be automatically set as the reason.

In a similar fashion, to set the health status to UP and clear the reason:

health.SetHealthy()

Alternatively, to set the status and the reason individually you can use health.SetStatus(<status>) where <status> is health.Up or health.Down:

health.SetStatus(health.Up)
health.SetStatus(health.Down)

As for the reason:

health.SetReason("database is unreachable")

Generally speaking, you'd only want to include a reason if the status is Down, but you can do as you desire.

For the sake of convenience, you can also use health.SetStatusAndReason(<status>, <reason>) instead of doing health.SetStatus(<status>) and health.SetReason(<reason>) separately.

Complete example

package main

import (
    "net/http"
    "time"

    "github.com/TwiN/health"
)

func main() {
    router := http.NewServeMux()
    router.Handle("/health", health.Handler())
    server := &http.Server{
        Addr:         "0.0.0.0:8080",
        Handler:      router,
        ReadTimeout:  15 * time.Second,
        WriteTimeout: 15 * time.Second,
        IdleTimeout:  15 * time.Second,
    }
    server.ListenAndServe()
}

Using health with third party router/mux/http libraries

Here's an example with fiber:

healthHandler := health.Handler().WithJSON(true)

app := fiber.New()
app.Get("/health", func(c *fiber.Ctx) error {
    statusCode, body := healthHandler.GetResponseStatusCodeAndBody()
    return c.Status(statusCode).Send(body)
})
app.Listen(":8080")