Documentation
¶
Overview ¶
Package server provides the HTTP server scaffolding used by standalone checkers. It is separated from the core checker package so that plugin and builtin builds, which never expose an HTTP endpoint, do not pay the cost of net/http, html/template, and their transitive dependencies.
Index ¶
- type Interactive
- type Server
- func (s *Server) Close() error
- func (s *Server) Handle(pattern string, handler http.Handler)
- func (s *Server) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
- func (s *Server) Handler() http.Handler
- func (s *Server) ListenAndServe(addr string) error
- func (s *Server) TrackWork(next http.Handler) http.Handler
- type Siblings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Interactive ¶
type Interactive interface {
// RenderForm returns the fields the human must fill in to bootstrap
// a check. Typically a minimal set (domain name, nameserver to
// query, …) that ParseForm expands into the full CheckerOptions
// that Collect expects.
RenderForm() []checker.CheckerOptionField
// ParseForm reads the submitted form and returns the CheckerOptions
// ready to feed Collect. It is the checker's responsibility to do
// whatever lookups or resolutions are needed to populate fields
// that would normally be auto-filled by happyDomain. Returning an
// error causes the SDK to re-render the form with the error
// displayed.
ParseForm(r *http.Request) (checker.CheckerOptions, error)
}
Interactive is an optional interface that observation providers can implement to expose a human-facing web form usable standalone, outside of a happyDomain host. Detect support with a type assertion: _, ok := provider.(server.Interactive).
When the provider implements it, Server binds GET and POST on /check. GET renders an HTML form built from RenderForm(). POST calls ParseForm to obtain the checker.CheckerOptions, then runs the standard pipeline (Collect, Evaluate, GetHTMLReport, ExtractMetrics) and renders a consolidated result page.
Unlike /evaluate, which relies on happyDomain to fill AutoFill-backed options from execution context, an Interactive implementation is responsible for resolving whatever it needs from the human inputs (typically via direct DNS queries) before Collect runs.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a generic HTTP server for external checkers. It always exposes /health and /collect. If the provider implements checker.CheckerDefinitionProvider, it also exposes /definition and /evaluate. If the provider implements checker.CheckerHTMLReporter or checker.CheckerMetricsReporter, it also exposes /report. If the provider implements Interactive, it also exposes /check (a human-facing web form).
Security: Server does not perform any authentication or authorization. It is intended to be run behind a reverse proxy or in a trusted network where access control is handled externally (e.g. by the happyDomain server).
func New ¶
func New(provider checker.ObservationProvider) *Server
New creates a new checker HTTP server backed by the given provider. Additional endpoints are registered based on optional interfaces the provider implements.
New also starts a background goroutine that samples the in-flight request count every loadSampleInterval to compute the load averages reported on /health. Call Close to stop it.
func (*Server) Close ¶
Close stops the background load-average sampler goroutine. It is safe to call multiple times; subsequent calls are no-ops. Close does not shut down any underlying http.Server, callers own that lifecycle.
func (*Server) Handle ¶
Handle registers an auxiliary handler on the server's mux. Must be called before ListenAndServe or Handler(). Custom handlers are not tracked by TrackWork; wrap them explicitly if you want them counted in /health load.
func (*Server) HandleFunc ¶
HandleFunc is the http.HandlerFunc-flavoured counterpart of Handle.
func (*Server) Handler ¶
Handler returns the http.Handler for this server, allowing callers to embed it in a custom server or add middleware.
func (*Server) ListenAndServe ¶
ListenAndServe starts the HTTP server on the given address and blocks until the server stops.
ListenAndServe installs a SIGINT/SIGTERM handler that triggers a graceful shutdown: new connections are refused and in-flight requests are given up to shutdownTimeout to complete. The background load-average sampler is stopped via Close before returning. Callers who need their own signal handling or shutdown semantics should use Handler() and run their own http.Server instead.
If the consumer's flag.Parse() set the SDK-registered -healthcheck flag, ListenAndServe never starts the server: it probes /health on addr and calls os.Exit(0) on success or os.Exit(1) on failure. This is what lets a scratch-based Docker image use the binary itself as its HEALTHCHECK probe.
type Siblings ¶
type Siblings interface {
RelatedProviders() []checker.ObservationProvider
}
Siblings is an optional interface an interactive ObservationProvider can co-implement to declare sibling providers whose Collect the SDK runs in-process during /check. Their results are exposed as RelatedObservations on ObservationGetter and ReportContext, mirroring the cross-checker lineage a happyDomain host resolves.
For each sibling the SDK seeds options from the primary and, when the primary implements DiscoveryPublisher, writes its entries into any sibling option tagged AutoFill == checker.AutoFillDiscoveryEntries. Sibling errors are logged and skipped so the primary result still reaches the user.
Source Files
¶
- healthcheck.go
- interactive.go
- server.go