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.
Key exported symbols: New constructs the handler; Config controls probe paths, per-probe Checker functions, the Config.Skip bypass predicate, and Config.CheckerTimeout (default DefaultCheckerTimeout, 5 s). Set Config.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. Invalid paths (missing leading '/') or overlapping enabled paths cause a panic at initialization.
Response format: 200 {"status":"ok"} / 503 {"status":"unavailable"}. HEAD requests return the status code with no body.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware
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