Documentation
¶
Overview ¶
Package healthcheck provides Kubernetes-style health probe middleware for celeris.
The middleware intercepts GET/HEAD requests matching configurable probe paths (default "/livez", "/readyz", "/startupz") and returns a JSON status response. Non-matching requests pass through with zero overhead.
Basic usage (all probes return 200):
server.Use(healthcheck.New())
Custom readiness check:
server.Use(healthcheck.New(healthcheck.Config{
ReadyChecker: func(_ *celeris.Context) bool {
return db.Ping() == nil
},
}))
Each checker is guarded by Config.CheckerTimeout (default 5s); if it does not return in time the probe responds 503. Set CheckerTimeout to FastPathTimeout for trivial checkers that cannot block (runs inline, no goroutine overhead). Panicking checkers are recovered and return 503.
Setting a probe path to "" disables that probe. Config.Skip bypasses the middleware before path matching.
Invalid paths (missing leading '/') or overlapping enabled paths cause a panic at initialization. These are programming errors caught early.
Response format: 200 {"status":"ok"} / 503 {"status":"unavailable"}. HEAD requests return the status code with no body.
Index ¶
Examples ¶
Constants ¶
const ( DefaultLivePath = "/livez" DefaultReadyPath = "/readyz" DefaultStartPath = "/startupz" )
Exported path constants for the default probe endpoints.
const DefaultCheckerTimeout = 5 * time.Second
DefaultCheckerTimeout is the default timeout for health checkers.
const FastPathTimeout = -1 * time.Second
FastPathTimeout disables the goroutine/channel/context timeout machinery and runs checkers synchronously inline. Use this for trivial checkers that cannot block.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a healthcheck middleware with the given config.
Example ¶
package main
import (
"github.com/goceleris/celeris"
"github.com/goceleris/celeris/middleware/healthcheck"
)
func main() {
server := celeris.New(celeris.Config{})
// All probes return 200 by default.
server.Use(healthcheck.New())
}
Output:
Example (CustomChecker) ¶
package main
import (
"github.com/goceleris/celeris"
"github.com/goceleris/celeris/middleware/healthcheck"
)
func main() {
server := celeris.New(celeris.Config{})
server.Use(healthcheck.New(healthcheck.Config{
ReadyChecker: func(_ *celeris.Context) bool {
// Check database connectivity, etc.
return true
},
}))
}
Output:
Example (CustomPaths) ¶
package main
import (
"github.com/goceleris/celeris"
"github.com/goceleris/celeris/middleware/healthcheck"
)
func main() {
server := celeris.New(celeris.Config{})
server.Use(healthcheck.New(healthcheck.Config{
LivePath: "/health/live",
ReadyPath: "/health/ready",
StartPath: "/health/startup",
}))
}
Output:
Example (FastPath) ¶
package main
import (
"github.com/goceleris/celeris"
"github.com/goceleris/celeris/middleware/healthcheck"
)
func main() {
server := celeris.New(celeris.Config{})
server.Use(healthcheck.New(healthcheck.Config{
CheckerTimeout: healthcheck.FastPathTimeout,
}))
}
Output:
Types ¶
type Checker ¶
Checker reports a probe's health status. The context is provided so checkers can inspect the request or respect deadlines.
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths is a list of request paths to exclude from healthcheck
// interception. Matching is exact (no glob or prefix support).
SkipPaths []string
// LivePath is the URL path for the liveness probe.
// Default: "/livez".
LivePath string
// ReadyPath is the URL path for the readiness probe.
// Default: "/readyz".
ReadyPath string
// StartPath is the URL path for the startup probe.
// Default: "/startupz".
StartPath string
// LiveChecker reports whether the process is alive.
// Default: always true.
LiveChecker Checker
// ReadyChecker reports whether the service can accept traffic.
// Default: always true.
ReadyChecker Checker
// StartChecker reports whether initial startup has completed.
// Default: always true.
StartChecker Checker
// CheckerTimeout is the maximum duration to wait for a checker to
// complete. If the checker does not return within this duration,
// the probe returns 503 unavailable.
//
// Special values:
// 0 — use default (5s)
// FastPathTimeout — run synchronously without goroutine/channel/context
// overhead (recommended for trivial checkers that
// cannot block; use the FastPathTimeout constant
// rather than a raw negative literal)
//
// Default: 5s.
CheckerTimeout time.Duration
}
Config defines the healthcheck middleware configuration.
Source Files