controls

type ChannelProvider ¶

type ChannelProvider interface {
	Messages() chan Message
	Errors() chan error
	Signals() chan os.Signal
}

ChannelProvider provides access to controller channels.

type CheckResult ¶

type CheckResult struct {
	// Status is the health status.
	Status CheckStatus
	// Message provides human-readable detail about the check result.
	Message string
	// Timestamp is when this result was produced.
	Timestamp time.Time
}

CheckResult represents the outcome of a health check.

type CheckStatus ¶

type CheckStatus int

CheckStatus represents the health state of a check.

const (
	// CheckHealthy indicates the check passed.
	CheckHealthy CheckStatus = iota
	// CheckDegraded indicates the check passed but with warnings.
	// Maps to OverallHealthy: true with Status: "DEGRADED".
	CheckDegraded
	// CheckUnhealthy indicates the check failed.
	// Maps to OverallHealthy: false with Status: "ERROR".
	CheckUnhealthy
)

type CheckType ¶

type CheckType int

CheckType determines which health endpoint(s) a check contributes to.

const (
	// CheckTypeReadiness contributes to the readiness endpoint.
	CheckTypeReadiness CheckType = iota
	// CheckTypeLiveness contributes to the liveness endpoint.
	CheckTypeLiveness
	// CheckTypeBoth contributes to both liveness and readiness endpoints.
	CheckTypeBoth
)

type Child ¶ added in v0.4.0

type Child struct {
	// Name identifies the child within its supervisor.
	Name string

	// Start runs the child. Returning nil means it finished cleanly and will
	// not be restarted; returning an error starts the restart policy.
	Start StartFunc

	// Stop is called when the child is detached or the supervisor stops. It is
	// optional: cancelling the context passed to Start is the primary mechanism.
	Stop StopFunc

	// ValidError identifies errors that mean a clean stop rather than a failure,
	// http.ErrServerClosed being the case it exists for. An error it accepts ends
	// the child without a restart and without a [Failure], exactly as a
	// [Controller]'s WithValidError does for a Service.
	//
	// Per child rather than per supervisor, because a supervisor may hold children
	// of very different kinds and one predicate for all of them is the wrong unit.
	// Nil means no error is exempt.
	ValidError ValidErrorFunc

	// RestartPolicy governs restarts. Nil means never restart: the child runs
	// once and its outcome is final.
	//
	// The restart rules are a Service's rules, read through the same helpers,
	// including that MaxRestarts <= 0 means UNLIMITED rather than none. The same
	// type is used deliberately: a caller should configure restart behaviour one
	// way whether the thing being restarted is registered or attached, and two
	// rules with the same fields is the divergence nobody notices until they
	// disagree.
	//
	// Two of the type's fields are inert here. HealthFailureThreshold and
	// HealthCheckInterval drive a Service's health-based restarts through its
	// Status probe, and a Child has no probe to read. Setting them changes
	// nothing rather than failing, which is why it is said here.
	//
	// An expected terminal error is [Child.ValidError] rather than a policy field,
	// matching where a Service declares it.
	//
	// The value is copied at [Supervisor.Attach], so a caller may reuse or edit
	// its policy struct afterwards without racing the supervision goroutine.
	RestartPolicy *RestartPolicy
}

Child is one supervised unit.

Unlike a Service, a child is not a requirement for the process to operate: see Supervisor for what that distinction buys.

type ChildState ¶ added in v0.4.0

type ChildState string

ChildState is what a supervisor can say about a child.

const (
	// ChildPending means the child is attached and its Start has not been called,
	// because the supervisor has not started yet.
	ChildPending ChildState = "pending"

	// ChildRunning means the child's Start has not returned.
	ChildRunning ChildState = "running"

	// ChildBackoff means the child failed and is waiting out its restart backoff.
	// Reporting it as running would describe a dead child as a live one for as
	// long as MaxBackoff.
	ChildBackoff ChildState = "backoff"

	// ChildFailed means the child exhausted its restart policy.
	ChildFailed ChildState = "failed"

	// ChildStopped means the child returned cleanly or was stopped.
	ChildStopped ChildState = "stopped"
)

type ChildStatus ¶ added in v0.4.0

type ChildStatus struct {
	State    ChildState
	Restarts int
	Panics   int
	LastErr  error
}

ChildStatus is a child's observable state.

type Configurable ¶

type Configurable interface {
	SetErrorsChannel(errs chan error)
	SetMessageChannel(control chan Message)
	SetSignalsChannel(sigs chan os.Signal)
	SetWaitGroup(wg *sync.WaitGroup)
	SetShutdownTimeout(d time.Duration)
	SetLogger(l *slog.Logger)
}

Configurable provides controller configuration setters.

These setters mutate channel and logger fields that controller goroutines read after Start. They carry no internal synchronization and must only be called during construction — before Start — which is how the WithX ControllerOpt options apply them inside NewController. Calling any setter after Start races the running goroutines and is a programming error.

type Controllable ¶

type Controllable interface {
	Runner
	HealthReporter
	StateAccessor
	Configurable
	ChannelProvider
}

Controllable is the full controller interface, composed of all role-based interfaces. Prefer using the narrower interfaces (Runner, HealthReporter, Configurable, etc.) where possible.

type Controller ¶

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

Controller orchestrates the lifecycle of registered services: concurrent startup, health monitoring, ordered (reverse-registration) shutdown, and signal handling.

func NewController(ctx context.Context, opts ...ControllerOpt) *Controller

package main

import (
	"context"
	"fmt"
	"time"

	"gitlab.com/phpboyscout/go/controls"
)

func main() {
	ctx := context.Background()

	// Create a controller. No OS signal handler is installed by default; a
	// standalone daemon that owns signals adds controls.WithSignals().
	controller := controls.NewController(ctx)

	// Register an HTTP service
	controller.Register("http-api",
		controls.WithStart(func(ctx context.Context) error {
			fmt.Println("HTTP server starting")
			return nil
		}),
		controls.WithStop(func(ctx context.Context) {
			fmt.Println("HTTP server stopping")
		}),
		controls.WithStatus(func() error {
			return nil // healthy
		}),
	)

	// Start all services
	controller.Start()

	// Graceful shutdown
	time.Sleep(10 * time.Millisecond)
	controller.Stop()
	controller.Wait()
}

Output:

func (c *Controller) Errors() chan error

func (c *Controller) GetCheckResult(name string) (CheckResult, bool)

func (c *Controller) GetContext() context.Context

func (c *Controller) GetLogger() *slog.Logger

func (c *Controller) GetServiceInfo(name string) (ServiceInfo, bool)

func (c *Controller) GetState() State

func (c *Controller) IsRunning() bool

func (c *Controller) IsStopped() bool

func (c *Controller) IsStopping() bool

func (c *Controller) Liveness() HealthReport

func (c *Controller) Messages() chan Message

func (c *Controller) Readiness() HealthReport

func (c *Controller) Register(id string, opts ...ServiceOption)

func (c *Controller) RegisterHealthCheck(check HealthCheck) error

func (c *Controller) SetErrorsChannel(errs chan error)

func (c *Controller) SetLogger(l *slog.Logger)

func (c *Controller) SetMessageChannel(messages chan Message)

func (c *Controller) SetShutdownTimeout(d time.Duration)

func (c *Controller) SetSignalsChannel(signals chan os.Signal)

func (c *Controller) SetState(state State)

func (c *Controller) SetWaitGroup(wg *sync.WaitGroup)

func (c *Controller) Signals() chan os.Signal

func (c *Controller) Start()

func (c *Controller) Status() HealthReport

func (c *Controller) Stop()

func (c *Controller) Wait()

func (c *Controller) WaitContext(ctx context.Context) error

func (c *Controller) WaitGroup() *sync.WaitGroup

type ControllerOpt ¶

type ControllerOpt func(Configurable)

ControllerOpt is a functional option for configuring a Controller.

func WithLogger(l *slog.Logger) ControllerOpt

func WithShutdownTimeout(d time.Duration) ControllerOpt

func WithSignals() ControllerOpt

func WithValidError(fn ValidErrorFunc) ControllerOpt

type Failure ¶ added in v0.4.0

type Failure struct {
	// Name is the child that failed.
	Name string

	// Err is the error it last returned, wrapped to say restarts were exhausted:
	// errors.Is matches [ErrRestartsExhausted] and the child's own error.
	Err error

	// Restarts is how many were attempted before giving up.
	Restarts int

	// Panicked reports whether the last run ended in a recovered panic rather
	// than a returned error. A bug and a failure are different things, and a
	// consumer deciding how to proceed wants to know which it has.
	Panicked bool
}

Failure is a child that has exhausted its restart policy.

It is delivered to the consumer because whether that child mattered is the consumer's judgement, not the supervisor's.

type Generational ¶ added in v0.5.0

type Generational[R any] struct {
	// Build creates everything one generation needs. It is called once per
	// Start, and anything it acquires that needs releasing must be reachable
	// from the returned R, or it leaks. That obligation is the whole contract
	// this type places on a consumer.
	Build func(ctx context.Context) (R, error)

	// Release frees everything Build acquired. It must be idempotent, and it
	// must be safe to call concurrently with in-flight work that still holds a
	// lease, because a lease that outlives the stop budget is disowned rather
	// than waited for.
	//
	// A nil error means every resource is gone, and that is the only thing that
	// permits a new generation to start.
	Release func(ctx context.Context, r R) error

	// Probe reports the health of the current generation. Optional; nil means
	// always healthy while running.
	Probe func(r R) error

	// ReleaseAttempt is the budget each call to Release gets. The disposer
	// retries on this interval until Release returns nil, so it is a retry
	// interval rather than a deadline for the whole release. Zero or negative
	// selects 250ms (spec 0007 D1, D2).
	ReleaseAttempt time.Duration
	// contains filtered or unexported fields
}

Generational owns one generation of R at a time, for a service that can be stopped and started again in-process.

Why this exists ¶

A restart re-invokes a service's StartFunc, so anything that closure captured is shared across generations. Five times across this estate a module has captured something single-use — a supervisor, a gRPC server, an http.Server, an exit status, a per-tenant handle — and then failed in one of two ways: the restart could not work, or the stopped thing carried on looking healthy. Two properties answer those two failures, and neither subsumes the other:

• a new generation is built whole, from one recipe, never revived; and
• a stopped generation refuses further use, loudly.

This type provides both. A Supervisor is single-use by design, so a service that owns one and must survive a restart wraps it here rather than reaching for a restartable supervisor.

Using it ¶

g := &controls.Generational[*run]{
	Build:   func(ctx context.Context) (*run, error) { return open(ctx) },
	Release: func(ctx context.Context, r *run) error { return r.close(ctx) },
}

controller.Register("thing",
	controls.WithStart(g.Start),
	controls.WithStopErr(g.Stop),
	controls.WithStatus(g.Healthy),
)

The zero value is not usable: Build and Release are required. It is safe for concurrent use, and Use is on the hot path — it takes no mutex.

package main

import (
	"context"
	"fmt"

	"gitlab.com/phpboyscout/go/errors"

	"gitlab.com/phpboyscout/go/controls"
)

type conn struct{ id int }

func main() {
	built := 0

	g := &controls.Generational[*conn]{
		Build: func(context.Context) (*conn, error) {
			built++

			return &conn{id: built}, nil
		},
		Release: func(_ context.Context, c *conn) error {
			fmt.Println("released", c.id)

			return nil
		},
	}

	ctx := context.Background()
	show := func(c *conn) error {
		fmt.Println("using", c.id, "in generation", g.Generation())

		return nil
	}

	fmt.Println("use before start:", errors.Is(g.Use(show), controls.ErrNoGeneration))

	_ = g.Start(ctx)
	_ = g.Use(show)
	fmt.Println("second start:", errors.Is(g.Start(ctx), controls.ErrGenerationRunning))

	_ = g.Stop(ctx)
	fmt.Println("use after stop:", errors.Is(g.Use(show), controls.ErrNoGeneration), "generation", g.Generation())

	_ = g.Start(ctx)
	_ = g.Use(show)
	_ = g.Stop(ctx)
}

Output:
use before start: true
using 1 in generation 1
second start: true
released 1
use after stop: true generation 0
using 2 in generation 2
released 2

func (g *Generational[R]) Generation() uint64

func (g *Generational[R]) Healthy() error

func (g *Generational[R]) Start(ctx context.Context) error

func (g *Generational[R]) Stop(ctx context.Context) error

func (g *Generational[R]) Use(fn func(R) error) error

type HealthCheck ¶

type HealthCheck struct {
	// Name is the unique identifier for this check.
	Name string
	// Check is the function that performs the health check.
	// It receives a context with the check's timeout applied.
	Check func(ctx context.Context) CheckResult
	// Timeout is the maximum duration for a single check execution.
	// Default: 5s.
	Timeout time.Duration
	// Interval is the polling interval for async checks.
	// Zero means synchronous (run on every health request).
	Interval time.Duration
	// Type determines which health endpoints this check feeds into.
	// Default: CheckTypeReadiness.
	Type CheckType
}

HealthCheck defines a named health check function.

type HealthCheckReporter ¶

type HealthCheckReporter interface {
	HealthReporter
	// GetCheckResult returns the latest result for a named health check.
	GetCheckResult(name string) (CheckResult, bool)
}

HealthCheckReporter extends HealthReporter with check-specific queries.

type HealthReport ¶

type HealthReport struct {
	OverallHealthy bool `json:"overall_healthy"`

	// State is the controller's lifecycle state when the report was taken.
	//
	// Carried on every report, including Status, which is explicitly not a gate.
	// A reader that only sees OverallHealthy cannot tell an unhealthy service
	// from a controller that has begun shutting down, and those want different
	// responses.
	State State `json:"state"`

	Services []ServiceStatus `json:"services"`
}

HealthReport is the aggregate health status across all registered services.

type HealthReporter ¶

type HealthReporter interface {
	Status() HealthReport
	Liveness() HealthReport
	Readiness() HealthReport
	GetServiceInfo(name string) (ServiceInfo, bool)
}

HealthReporter provides read access to service health, liveness, and readiness reports, and to per-service runtime information. Handlers and transports that only need to query health should depend on this interface rather than the full Controllable.

type Message ¶

type Message string

Message represents a control message sent to the controller (e.g. "stop").

const (
	Stop Message = "stop"
)

type ProbeFunc ¶

type ProbeFunc func() error

ProbeFunc is a health check function for liveness or readiness probes.

type RestartPolicy ¶

type RestartPolicy struct {
	MaxRestarts            int
	InitialBackoff         time.Duration
	MaxBackoff             time.Duration
	HealthFailureThreshold int
	HealthCheckInterval    time.Duration
	// RestartResetInterval is how long a service must run healthily before its
	// consecutive-failure restart counter is reset to zero. Zero selects
	// DefaultRestartResetInterval. The count therefore measures consecutive
	// failures, not lifetime restarts.
	RestartResetInterval time.Duration
}

RestartPolicy defines how a service should be restarted on failure.

type Runner ¶

type Runner interface {
	Start()
	Stop()
	IsRunning() bool
	IsStopped() bool
	IsStopping() bool
	Register(id string, opts ...ServiceOption)
}

Runner provides service lifecycle operations.

type Service ¶

type Service struct {
	Name          string
	Start         StartFunc
	Stop          StopFunc
	StopErr       StopErrFunc
	Status        StatusFunc
	Liveness      ProbeFunc
	Readiness     ProbeFunc
	RestartPolicy *RestartPolicy
}

Service represents a managed background service with start/stop lifecycle, health probes, and optional restart policy.

type ServiceInfo ¶

type ServiceInfo struct {
	Name         string
	RestartCount int
	LastStarted  time.Time
	LastStopped  time.Time
	Error        error

	// StopErr is how the last stop ended: nil when every resource was
	// released, non-nil when it was not, and always nil for a service
	// registered with [WithStop], which cannot report either way.
	//
	// A panic inside a stop is contained and recorded here rather than ending
	// the process.
	StopErr error
}

ServiceInfo holds runtime metadata about a registered service.

type ServiceOption ¶

type ServiceOption func(*Service)

ServiceOption is a functional option for configuring a Service.

func WithLiveness(fn ProbeFunc) ServiceOption

package main

import (
	"context"
	"net/http"

	"gitlab.com/phpboyscout/go/controls"
)

func main() {
	controller := controls.NewController(context.Background())

	controller.Register("api",
		controls.WithStart(func(ctx context.Context) error { return nil }),
		controls.WithLiveness(func() error {
			// Check if the service can respond
			resp, err := http.Get("http://localhost:8080/healthz")
			if err != nil {
				return err
			}

			_ = resp.Body.Close()

			return nil
		}),
	)

	_ = controller
}

Output:

func WithReadiness(fn ProbeFunc) ServiceOption

func WithRestartPolicy(policy RestartPolicy) ServiceOption

package main

import (
	"context"
	"time"

	"gitlab.com/phpboyscout/go/controls"
)

func main() {
	controller := controls.NewController(context.Background())

	controller.Register("worker",
		controls.WithStart(func(ctx context.Context) error {
			return nil
		}),
		controls.WithRestartPolicy(controls.RestartPolicy{
			MaxRestarts:    3,
			InitialBackoff: time.Second,
			MaxBackoff:     30 * time.Second,
		}),
	)

	_ = controller
}

Output:

func WithRestartResetInterval(d time.Duration) ServiceOption

func WithStart(fn StartFunc) ServiceOption

func WithStatus(fn StatusFunc) ServiceOption

func WithStop(fn StopFunc) ServiceOption

func WithStopErr(fn StopErrFunc) ServiceOption

package main

import (
	"context"
	"fmt"

	"gitlab.com/phpboyscout/go/errors"

	"gitlab.com/phpboyscout/go/controls"
)

func main() {
	controller := controls.NewController(context.Background())

	controller.Register("holder",
		controls.WithStart(func(ctx context.Context) error {
			<-ctx.Done()

			return ctx.Err()
		}),
		controls.WithStopErr(func(context.Context) error {
			return errors.New("listener still open")
		}),
	)

	controller.Start()
	controller.Stop()
	controller.Wait()

	info, _ := controller.GetServiceInfo("holder")
	fmt.Println("stop error:", info.StopErr)
}

Output:
stop error: listener still open

type ServiceStatus ¶

type ServiceStatus struct {
	Name   string `json:"name"`
	Status string `json:"status"` // "OK", "ERROR"
	Error  string `json:"error,omitempty"`
}

ServiceStatus is the health status of a single service, used in HealthReport.

type Services ¶

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

Services manages the collection of registered services and their lifecycle.

type StartFunc ¶

type StartFunc func(context.Context) error

StartFunc is the callback invoked to start a service. It receives a context that is cancelled when the controller shuts down.

A restart calls this again, so what the closure captured is shared ¶

Everything this function's closure captured is shared across generations and must be safe to use again. Anything single-use or generation-scoped — a listener, a server, a supervisor, an exit status, a per-tenant handle — must be built INSIDE the run that consumes it, or the second run gets the first run's corpse.

The two failures this causes are worth naming, because they look nothing alike. Either the restart cannot work at all, or the stopped thing carries on looking healthy — a status cell that was never cleared, a handle whose backing is gone. So: a stopped generation must refuse further use, loudly, and a new generation is built whole, from one recipe, never revived and never partially reused.

Generational provides both for a service that needs them. A service that genuinely captures nothing single-use needs neither, and most do not.

type State ¶

type State string

State represents the lifecycle state of the controller.

It moves in one direction: NeverStarted to Running, then either to Stopping and Stopped or to UnableToStart and then Stopping and Stopped. Unknown is not part of that sequence; it means the value could not be determined.

const (
	// Unknown means the state could not be determined. It is what [Controller.GetState]
	// reports for a zero-valued Controller, i.e. one built without NewController,
	// which is otherwise undetectable because State is a string type and its zero
	// value is the empty string.
	Unknown State = "unknown"

	// NeverStarted means the controller was constructed and Start has not been
	// called. Registration is only honoured in this state, and a Stop here leaves
	// it unchanged: stopping something that never started is a no-op, so the
	// controller stays startable.
	NeverStarted State = "never_started"

	// Running means Start has been called and shutdown has not begun. It is the
	// only state in which the controller reports ready.
	Running State = "running"

	// UnableToStart means a registered service has proven it will never start: it
	// has failed without ever starting cleanly and has exhausted its restart
	// policy. Nothing is stopped, and the error still reaches the error channel;
	// what changes is that the controller stops reporting ready, so an
	// orchestrator routes no traffic to a process that cannot do its job.
	//
	// A service that fails and then recovers on a restart never reaches this, and
	// neither does one that started cleanly and failed later. Both conditions are
	// required, so the state is terminal rather than something readiness flaps on
	// through a slow boot.
	UnableToStart State = "unable_to_start"

	Stopping State = "stopping"
	Stopped  State = "stopped"
)

type StateAccessor ¶

type StateAccessor interface {
	GetState() State
	SetState(state State)
	GetContext() context.Context
	GetLogger() *slog.Logger
}

StateAccessor provides access to controller state and context, and is meant to be consumed AND implemented outside this module.

The setter is deliberate, and is why this is not a read-only interface: a consumer driving a controller it owns needs to be able to say what state it is in, and a consumer implementing this interface over its own type needs the same surface the Controller has. It was proposed for removal once on the reading that this was a read-side view, which the doc comment then said it was; see wiki spec 0003 D7.

SetState mutates a field the control goroutines read, so the contract is the one Configurable states: call it during construction, or on a controller you own. Reaching into a running controller from elsewhere races those goroutines, and since readiness is gated on the state (0003 D2) it can also take a healthy process out of rotation.

type StatusFunc ¶

type StatusFunc func() error

StatusFunc is the callback invoked to check a service's health. Returns nil if healthy, an error otherwise.

It must report the CURRENT run. A status cell captured by the closure and never cleared between generations keeps reporting the previous run's failure, which fails the health threshold, which restarts the service, which reports the same stale failure — a service churning to restart exhaustion without one log line naming the cause. See StartFunc on what a restart shares.

type StopErrFunc ¶ added in v0.5.0

type StopErrFunc func(context.Context) error

StopErrFunc stops a service and reports how the stop ended.

A nil error means every resource the run acquired has been released. A non-nil one means the budget expired or release failed, and the service may still be holding something — a listener, a connection, a subscription.

It is recorded, not acted upon ¶

The Controller stores the result in ServiceInfo and changes nothing else: no restart is refused and no policy is altered on the strength of it. Knowing the answer is the prerequisite, and making a restart depend on it is a behaviour change for every consumer and a separate decision.

Before this existed a stop that ignored its context was abandoned at the deadline silently, and nothing anywhere recorded that it had happened.

type StopFunc ¶

type StopFunc func(context.Context)

StopFunc is the callback invoked to stop a service gracefully. The context carries the shutdown timeout.

type Supervisor ¶ added in v0.4.0

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

Supervisor runs children that attach and detach while the process is running.

Registered means required; attached does not ¶

A Service registered with a Controller is a requirement for operation: if its probe fails, the whole process reports unready. A child attached to a Supervisor is not. A failed child never makes the supervisor unready — at any proportion, including all of them — because whether that child mattered is the consumer's judgement and the consumer has the context to make it.

What the supervisor does instead is report CheckDegraded while any child has terminally failed, and hand the consumer a Failure to act on.

Which of the two to use ¶

A Controller manages a fixed set registered before Start, with ordered shutdown. A Supervisor manages a set that changes, with concurrent shutdown and no ordering between children — they must not depend on each other. A process has one Controller and may have several Supervisors.

A Supervisor is itself a Service: register it with a Controller and its children are supervised beneath it.

Single use, and what each call does out of order ¶

A Supervisor moves through new, running, stopping and stopped, and never goes back. Once shutdown begins, Supervisor.Attach and Supervisor.Start return ErrSupervisorStopped and Supervisor.Readiness reports it, rather than accepting work that will never be supervised.

Supervisor.Stop and Supervisor.Detach are bounded by the context they are given, including across a Child.Stop that blocks. A child that outlives the budget is abandoned rather than allowed to hold shutdown open, which is the same bargain Controller strikes at its own shutdown deadline.

package main

import (
	"context"
	"fmt"
	"time"

	"gitlab.com/phpboyscout/go/errors"

	"gitlab.com/phpboyscout/go/controls"
)

func main() {
	sup := controls.NewSupervisor(
		controls.WithOnFailure(func(f controls.Failure) {
			fmt.Println("failed:", f.Name, "after", f.Restarts, "restarts")
		}),
	)

	_ = sup.Attach(controls.Child{
		Name: "once",
		Start: func(context.Context) error {
			fmt.Println("once ran")

			return nil
		},
	})

	if err := sup.Start(context.Background()); err != nil {
		fmt.Println("start:", err)

		return
	}

	// Attaching after Start is the point: the child is supervised identically.
	_ = sup.Attach(controls.Child{
		Name: "worker",
		Start: func(ctx context.Context) error {
			<-ctx.Done()

			return ctx.Err()
		},
	})

	_ = sup.Attach(controls.Child{
		Name:  "broken",
		Start: func(context.Context) error { return errors.New("no such queue") },
	})

	for {
		h := sup.Health()
		if h["once"].State == controls.ChildStopped &&
			h["worker"].State == controls.ChildRunning &&
			h["broken"].State == controls.ChildFailed {
			break
		}

		time.Sleep(time.Millisecond)
	}

	// The failed child does not make the supervisor unready.
	fmt.Println("ready:", sup.Readiness() == nil)
	fmt.Println("check:", sup.HealthCheck("children").Check(context.Background()).Message)

	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	sup.Stop(ctx)
	fmt.Println("after stop:", errors.Is(sup.Readiness(), controls.ErrSupervisorStopped))
}

Output:
once ran
failed: broken after 0 restarts
ready: true
check: 1 of 3 supervised children have failed
after stop: true

func NewSupervisor(opts ...SupervisorOption) *Supervisor

func (s *Supervisor) Attach(c Child) error

func (s *Supervisor) Detach(ctx context.Context, name string) error

func (s *Supervisor) DroppedReports() int64

func (s *Supervisor) Failures() <-chan Failure

func (s *Supervisor) Health() map[string]ChildStatus

func (s *Supervisor) HealthCheck(name string) HealthCheck

func (s *Supervisor) Readiness() error

func (s *Supervisor) Start(ctx context.Context) error

func (s *Supervisor) Stop(ctx context.Context)

type SupervisorOption ¶ added in v0.4.0

type SupervisorOption func(*Supervisor)

SupervisorOption configures a Supervisor.

func WithOnFailure(fn func(Failure)) SupervisorOption

type ValidErrorFunc ¶

type ValidErrorFunc func(error) bool

ValidErrorFunc determines whether an error from a service is expected (e.g. http.ErrServerClosed) and should not trigger a restart.