probe

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package probe defines the core probe abstractions: a status enum, the Probe interface, function adapters and composition helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Asyncer

type Asyncer interface {
	Go(fn func())
	Wait()
}

Asyncer schedules concurrent work and waits for completion. A fresh Asyncer is obtained per check via AsyncerFactory.

type AsyncerFactory

type AsyncerFactory func() Asyncer

AsyncerFactory builds a fresh Asyncer per use.

func PoolFactory

func PoolFactory(maxConcurrent int) AsyncerFactory

PoolFactory returns an AsyncerFactory yielding fresh PoolAsyncer instances.

func SyncFactory

func SyncFactory() AsyncerFactory

SyncFactory returns an AsyncerFactory yielding SyncAsyncer.

type Bool

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

Bool is a toggleable probe. Its zero value is down. Status and reason are stored atomically and may be read or updated concurrently.

func NewBool

func NewBool() *Bool

func (*Bool) Check

func (b *Bool) Check(ctx context.Context) Status

func (*Bool) CheckResult added in v1.2.0

func (b *Bool) CheckResult(context.Context) Result

func (*Bool) Get

func (b *Bool) Get() bool

func (*Bool) Set

func (b *Bool) Set(v bool)

Set updates health and clears any previous reason.

func (*Bool) SetReason added in v1.2.0

func (b *Bool) SetReason(v bool, reason string)

SetReason explains an unhealthy flag. A healthy flag always clears reason.

type Composite

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

Composite runs multiple probes concurrently and aggregates their results.

func All

func All(probes ...Probe) *Composite

All returns a Composite that requires every probe to be StatusUp.

func Any

func Any(probes ...Probe) *Composite

Any returns a Composite that succeeds when at least one probe is StatusUp.

func New

func New(mode Mode, opts ...CompositeOption) *Composite

New builds a Composite with the given mode and options.

func (*Composite) Add

func (c *Composite) Add(p Probe) *Composite

Add appends a probe to the Composite. Safe for concurrent use.

func (*Composite) Check

func (c *Composite) Check(ctx context.Context) Status

Check runs all child probes concurrently and aggregates by Mode. Empty composites report StatusUp.

func (*Composite) CheckResult added in v1.2.0

func (c *Composite) CheckResult(ctx context.Context) Result

CheckResult aggregates observations in declaration order, including names and reasons of failing children. A successful Any has no failure reason.

func (*Composite) Len

func (c *Composite) Len() int

Len reports the current number of child probes.

type CompositeOption

type CompositeOption func(*Composite)

CompositeOption configures a Composite at construction time.

func WithAsyncer

func WithAsyncer(f AsyncerFactory) CompositeOption

WithAsyncer overrides the default AsyncerFactory used to run child probes.

type Detailed added in v1.2.0

type Detailed interface {
	Probe
	CheckResult(context.Context) Result
}

Detailed is an optional extension of Probe. Evaluate calls CheckResult instead of Check, so status and reason always describe the same observation.

type Func

type Func func(ctx context.Context) Status

Func adapts a plain function into a Probe.

func (Func) Check

func (f Func) Check(ctx context.Context) Status

type Mode

type Mode uint8

Mode controls how a Composite aggregates child probe statuses.

const (
	// ModeAll requires every child probe to be StatusUp.
	// The reported status is the worst observed.
	ModeAll Mode = iota
	// ModeAny requires at least one child probe to be StatusUp.
	// The reported status is the best observed.
	ModeAny
)

type Named

type Named struct {
	Probe
	// contains filtered or unexported fields
}

Named attaches a human-readable name to an underlying Probe.

func WithName

func WithName(name string, p Probe) *Named

func (*Named) CheckResult added in v1.2.0

func (n *Named) CheckResult(ctx context.Context) Result

func (*Named) Name

func (n *Named) Name() string

type PoolAsyncer

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

PoolAsyncer fans out to goroutines bounded by an optional semaphore. maxConcurrent <= 0 means unbounded.

func NewPoolAsyncer

func NewPoolAsyncer(maxConcurrent int) *PoolAsyncer

func (*PoolAsyncer) Go

func (p *PoolAsyncer) Go(f func())

func (*PoolAsyncer) Wait

func (p *PoolAsyncer) Wait()

type Probe

type Probe interface {
	Check(ctx context.Context) Status
}

Probe is anything that can report a health Status given a context.

Implementations MUST honor ctx cancellation: long-running checks (network I/O, external dependencies) must abort and return promptly when ctx is canceled. Callers such as runner.Runner and the HTTP/gRPC transports spawn a goroutine per check and rely on ctx to bound its lifetime — a probe that ignores ctx will leak a goroutine on every timeout.

The returned Status should reflect the most recent observation. Returning StatusUnknown is appropriate only when no determination could be made (e.g. ctx canceled before any work).

func FromError

func FromError(f func(ctx context.Context) error) Probe

FromError wraps an error-returning function: nil error -> StatusUp, otherwise StatusDown.

type Result added in v1.2.0

type Result struct {
	Status Status
	Reason string
}

Result is one observation. Reason explains a non-Up result; it is empty after recovery. Reasons can be exposed by HTTP handlers and reporters.

func Evaluate added in v1.2.0

func Evaluate(ctx context.Context, p Probe) Result

Evaluate performs exactly one check, preserving details where available.

func (Result) Normalized added in v1.2.0

func (r Result) Normalized() Result

Normalized clears obsolete reasons on healthy results.

type ResultFunc added in v1.2.0

type ResultFunc func(context.Context) Result

ResultFunc adapts a detailed check without breaking the Probe contract.

func (ResultFunc) Check added in v1.2.0

func (f ResultFunc) Check(ctx context.Context) Status

func (ResultFunc) CheckResult added in v1.2.0

func (f ResultFunc) CheckResult(ctx context.Context) Result

type Status

type Status uint8

Status represents the outcome of a probe check.

Zero value is StatusUnknown so a never-checked probe is distinguishable from one that has been checked and reported StatusUp.

const (
	StatusUnknown Status = iota
	StatusUp
	StatusDown
	StatusTimeout
)

func (Status) OK

func (s Status) OK() bool

OK reports whether the status is StatusUp.

func (Status) String

func (s Status) String() string

type SyncAsyncer

type SyncAsyncer struct{}

SyncAsyncer runs each func inline. Wait is a no-op.

func (SyncAsyncer) Go

func (SyncAsyncer) Go(f func())

func (SyncAsyncer) Wait

func (SyncAsyncer) Wait()

Jump to

Keyboard shortcuts

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