Services and restart policy reference¶

A service is a name plus a set of callbacks, registered with Register and described with ServiceOptions. This page lists the options, the contract each callback must honour, and every RestartPolicy field with its default.

Register¶

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

Register has no error return. Three consequences are worth knowing before you call it:

• Names are not checked for uniqueness. Registering two services under the same name is accepted. Both are started and stopped, both appear in every health report as separate entries with the same name, and GetServiceInfo(name) returns only the most recently registered one's info.
• Registration after Start is not supervised. The service is appended and logged as WARN "Register called after Start; service will not be supervised", but its StartFunc is never called, its StopFunc never runs, and no restart policy applies. It still appears in Status(), Liveness() and Readiness() — as "OK" if it has no probe. Treat that warning as a bug in your wiring.
• Both lifecycle callbacks are optional. A service with no WithStart gets a no-op that returns nil; one with no WithStop gets a no-op stop. Neither can be nil at run time, so neither can panic on a nil call.

Service options¶

What each callback must honour¶

StartFunc — func(ctx context.Context) error¶

It must return after its context is cancelled. A StartFunc that ignores cancellation pins its supervisor goroutine; the shutdown sequence abandons it at the deadline and names it in a WARN, but a bare Wait() then blocks forever. Use WaitContext when a service wraps third-party code that may not honour cancellation.

A panic inside a StartFunc is not recovered and crashes the process. Unlike stop callbacks and health probes, start callbacks have no recovery wrapper. Recover inside your own function if the work can panic.

StopFunc — func(ctx context.Context)¶

• The context is derived from context.Background() with the shutdown timeout — not from the already-cancelled controller context — so http.Server.Shutdown and friends can still drain in-flight work.
• It may be called more than once, and must be idempotent. Shutdown calls it once; a health-threshold restart calls it again before every restart of that service.
• It is not called between error-triggered restarts. When a StartFunc returns a genuine error and the policy restarts the service, StopFunc does not run in between; only a health-threshold restart stops the service first.
• A panic inside a StopFunc is recovered, and the shutdown sequence continues with the next service.
• Ignoring the context does not hang shutdown: the callback is abandoned at the deadline and left to finish on its own. The work it was doing is not completed.

StatusFunc and ProbeFunc — func() error¶

• Return nil for healthy, any error for unhealthy. The error text is copied into the report entry.
• Probes run inline while a report is built, so a slow probe delays the report and every caller waiting on it. Apply your own timeout inside a probe that does I/O.
• A panic in a probe called from Status(), Liveness() or Readiness() is recovered and reported as probe panicked: <value>.
• A panic in a WithStatus probe polled by the restart supervisor is not recovered and crashes the process. The recovery wrapper is applied on the report path only.

RestartPolicy fields¶

type RestartPolicy struct {
    MaxRestarts            int
    InitialBackoff         time.Duration
    MaxBackoff             time.Duration
    HealthFailureThreshold int
    HealthCheckInterval    time.Duration
    RestartResetInterval   time.Duration
}

Attaching a policy is what enables restarts at all. Without one, a StartFunc error is recorded in ServiceInfo, forwarded on the error channel, and the service is left stopped.

What the supervisor does when restarts run out¶

When the consecutive-failure counter reaches MaxRestarts, the supervisor stops supervising that service and records an error:

• from an error-driven restart loop, max restarts exceeded: <last start error> (the last error is wrapped, so errors.Is against it still matches);
• from a health-driven restart loop, max restarts exceeded on its own, because the health failure was recorded on ServiceInfo.Error rather than returned.

That error is stored on ServiceInfo.Error and forwarded on the error channel. The controller keeps running. A service exhausting its restarts — or failing with no policy at all — never shuts the process down; the controller stops only on Stop(), a signal it owns, or completion of the parent context.

ServiceInfo¶

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

GetServiceInfo returns a copy, so reading it never blocks the supervisor.

Ordering guarantees¶

• Startup is concurrent. One supervisor goroutine is launched per service in registration order; the controller does not wait for a StartFunc to return or a probe to pass before launching the next. There is no dependency ordering or readiness gate between services — gate inside your own StartFunc if you need one.
• Shutdown is sequential and reversed. Stop callbacks run one at a time in reverse registration order: register database then http-api, and http-api is stopped first.

Related¶

• Configure restart policy — the task-oriented recipe.
• The restart supervisor — why a clean start is never restarted.
• Defaults and timings — the same defaults alongside every other one.