health

package
v1.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package health provides upstream health monitoring with active probes, passive failure tracking, and health check history.

Index

Constants

View Source
const DefaultPath = "/_/health"

DefaultPath is the path probed when neither Config.Path nor the target names one. It is the path Forge services serve their health on.

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckResult

type CheckResult struct {
	TargetID  string        `json:"targetId"`
	TargetURL string        `json:"targetUrl"`
	Healthy   bool          `json:"healthy"`
	Latency   time.Duration `json:"latency"`
	Error     string        `json:"error,omitempty"`
	Timestamp time.Time     `json:"timestamp"`
}

CheckResult records a single health check outcome.

type Config

type Config struct {
	Enabled              bool          `json:"enabled" yaml:"enabled"`
	Interval             time.Duration `json:"interval" yaml:"interval"`
	Timeout              time.Duration `json:"timeout" yaml:"timeout"`
	Path                 string        `json:"path" yaml:"path"`
	FailureThreshold     int           `json:"failureThreshold" yaml:"failure_threshold"`
	SuccessThreshold     int           `json:"successThreshold" yaml:"success_threshold"`
	EnablePassive        bool          `json:"enablePassive" yaml:"enable_passive"`
	PassiveFailThreshold int           `json:"passiveFailThreshold" yaml:"passive_fail_threshold"`
}

Config configures upstream health checking.

Path is the health endpoint probed on every target that does not name its own (see HealthPathProvider). Leave it empty and the monitor still probes DefaultPath, but more leniently: any status below 500 counts as up, so an upstream that doesn't serve DefaultPath (and answers 404 or 401) keeps its route. A 5xx, a refused connection or a timeout still counts as a failure, which keeps a Forge service reporting 503 on its health endpoint out of rotation. Set Path, or give the target a health path, and the probe is strict: a status outside 200-399 fails it.

type Event

type Event struct {
	TargetID  string    `json:"targetId"`
	TargetURL string    `json:"targetUrl"`
	Healthy   bool      `json:"healthy"`
	Previous  bool      `json:"previous"`
	RouteID   string    `json:"routeId"`
	Timestamp time.Time `json:"timestamp"`
}

Event represents an upstream health change.

type HealthPathProvider

type HealthPathProvider interface {
	HealthPath() string
}

HealthPathProvider is an optional interface that targets can implement to specify a custom health check path instead of the global default. If a target implements this interface and returns a non-empty string, that path is used for health checks instead of the monitor's global Config.Path.

type History

type History struct {
	// contains filtered or unexported fields
}

History keeps a fixed-size ring buffer of health check results per upstream target. It is safe for concurrent use.

func NewHistory

func NewHistory(capacity int) *History

NewHistory creates a history tracker that stores up to capacity results per target.

func (*History) Get

func (hh *History) Get(targetID string) []CheckResult

Get returns all recorded results for a target in chronological order.

func (*History) GetSince

func (hh *History) GetSince(targetID string, since time.Time) []CheckResult

GetSince returns results for a target after the given time.

func (*History) Record

func (hh *History) Record(result CheckResult)

Record stores a health check result.

func (*History) Summary

func (hh *History) Summary(targetID string) Summary

Summary returns a Summary for the given target.

func (*History) Targets

func (hh *History) Targets() []string

Targets returns a list of all tracked target IDs.

func (*History) UptimePercent

func (hh *History) UptimePercent(targetID string, window time.Duration) float64

UptimePercent returns the percentage of healthy checks for a target over the last duration. Returns -1 if no data.

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor monitors the health of upstream targets.

func NewMonitor

func NewMonitor(config Config, logger forge.Logger) *Monitor

NewMonitor creates a new health monitor.

func (*Monitor) Deregister

func (hm *Monitor) Deregister(targetID string)

Deregister removes a target from health monitoring.

func (*Monitor) Health

func (hm *Monitor) Health(_ context.Context) error

Health returns an error if no targets are healthy (for HealthManager integration).

func (*Monitor) RecordPassiveFailure

func (hm *Monitor) RecordPassiveFailure(targetID string)

RecordPassiveFailure records a passive health check failure.

func (*Monitor) RecordPassiveSuccess

func (hm *Monitor) RecordPassiveSuccess(targetID string)

RecordPassiveSuccess records a passive health check success.

func (*Monitor) Register

func (hm *Monitor) Register(routeID string, target Target)

Register registers a target for health monitoring.

func (*Monitor) SetMetrics

func (hm *Monitor) SetMetrics(m *observability.Metrics)

SetMetrics sets where the monitor records its metrics: the duration of each check cycle and how many targets are healthy. Nil records none.

func (*Monitor) SetOnHealthChange

func (hm *Monitor) SetOnHealthChange(fn func(event Event))

SetOnHealthChange sets the health change callback.

func (*Monitor) Start

func (hm *Monitor) Start(ctx context.Context)

Start starts the health monitor background loop.

func (*Monitor) Stop

func (hm *Monitor) Stop()

Stop stops the health monitor. It is safe to call multiple times.

func (*Monitor) Tracks

func (hm *Monitor) Tracks(targetID string) bool

Tracks reports whether a target is currently registered for monitoring.

type Summary

type Summary struct {
	TargetID      string        `json:"targetId"`
	TotalChecks   int           `json:"totalChecks"`
	HealthyChecks int           `json:"healthyChecks"`
	UptimePercent float64       `json:"uptimePercent"`
	AvgLatency    time.Duration `json:"avgLatency"`
	LastCheck     *CheckResult  `json:"lastCheck,omitempty"`
}

Summary provides a summary of health check history for a target.

type Target

type Target interface {
	GetID() string
	GetURL() string
	IsHealthy() bool
	SetHealthy(healthy bool)
}

Target is a minimal interface for upstream targets used by the health monitor.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL