proberesponder

Proberesponder

Probe-responder is a package to deal with handling appropriate statuses for Kuberentes. Even though the statuses are specific to Kubernetes, it can be used in any context, and can later be updated to include more if required.

The sample below shows how to use proberesponder, all the statuses are "NOT OK" by default. This is intentional as the app is expected to explicitly update the respective status as OK which would be more accurate than being OK by default.

Extras

By default a bare bones HTTP server can be setup to respond to probe request. The default HTTP handlers provided does content negotiation and provides appropriate response for JSON, HTML & plain text. For any unidentified content type, it will respond with JSON.

AppendHealthResponse is a helper function with which you can maintain statuses of a dependency or similar. All the custom statuses set using this and the native ones (startup, live, ready) can be fetched as a map[string]string using HealthResponse.

DepProber is an extension package which provides basic dependency probing. Refer to tests for usage of Probe to setup your probes. e.g. you can ping the application's database periodically, and then use it for updating the app status to not live.

Sample usage

package main

import (
	"fmt"
	"time"

	"github.com/naughtygopher/proberesponder"
	pHTTP "github.com/naughtygopher/proberesponder/extensions/http"
)

func main() {
	pRes := proberesponder.New()

    // use the below server `srv` if you need more control of how it's started, shutdown etc.
	// srv := pHTTP.Server(pRes, "localhost", 1234)

	// setup an HTTP server to handle probe requests
	go pHTTP.StartHTTPServer(pRes, "localhost", 1234)

	// with set listener you can register a callback, for when any of the statuses
	// (startup, live, ready) is changed
	pRes.SetListener(func(status proberesponder.Statuskey, value bool) {
		fmt.Println(status, "changed to", value)
	})

	// Update the status of the app as Startup: OK
	pRes.SetNotStarted(false)

	// update the status of app as Live: OK
	pRes.SetNotLive(false)
	// update the status of app as Ready: OK
	pRes.SetNotReady(false)

	// set status of any service
	pRes.AppendHealthResponse("mydb", "OK")

	// retrieves all the statuses maintained by the proberesponder, it returns a map[string]string
	_ = pRes.HealthResponse()

	time.Sleep(time.Hour)
}

Below is an example of probe responses for HTTP requests using curl.

$ curl -H 'Accept: text/plain' localhost:1234/-/startup
mydb: OK | probe->live: OK: 2025-01-09T17:45:24+01:00 | probe->ready: OK: 2025-01-09T17:45:24+01:00 | probe->startup: OK: 2025-01-09T17:45:24+01:00 |

$ curl -H 'Accept: text/plain' localhost:1234/-/ready
probe->ready: OK: 2025-01-09T17:45:24+01:00 | probe->startup: OK: 2025-01-09T17:45:24+01:00 | mydb: OK | probe->live: OK: 2025-01-09T17:45:24+01:00 |

$ curl -H 'Accept: text/plain' localhost:1234/-/live
probe->startup: OK: 2025-01-09T17:45:24+01:00 | mydb: OK | probe->live: OK: 2025-01-09T17:45:24+01:00 | probe->ready: OK: 2025-01-09T17:45:24+01:00 |

The gopher

The gopher used here was created using Gopherize.me. Just like the handyman gopher here, proberesponder helps setup, well, a probe responder!