diff --git a/README.md b/README.md index e224fdf..49767f7 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ srv.Handle("POST /webhook", srv.TrackWork(myWebhookHandler)) log.Fatal(srv.ListenAndServe(":8080")) ``` -Patterns that collide with built-in routes panic at registration — +Patterns that collide with built-in routes panic at registration: pick non-overlapping paths. Custom handlers are not wrapped by the load-tracking middleware unless you opt in via `TrackWork`. @@ -74,7 +74,7 @@ type CheckerInteractive interface { pipeline, and returns a consolidated HTML page. `ParseForm` is where the checker replaces what happyDomain would normally -auto-fill (zone records, service payload, …) — typically by issuing its +auto-fill (zone records, service payload, …), typically by issuing its own DNS queries from the human-supplied inputs. ## License diff --git a/checker/interactive_test.go b/checker/interactive_test.go deleted file mode 100644 index 0a48512..0000000 --- a/checker/interactive_test.go +++ /dev/null @@ -1,245 +0,0 @@ -// Copyright 2020-2026 The happyDomain Authors -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package checker - -import ( - "context" - "errors" - "net/http" - "net/http/httptest" - "net/url" - "strings" - "testing" -) - -// interactiveProvider embeds testProvider and adds CheckerInteractive. -type interactiveProvider struct { - *testProvider - fields []CheckerOptionField - parseFn func(r *http.Request) (CheckerOptions, error) - parseErr error -} - -func (p *interactiveProvider) RenderForm() []CheckerOptionField { - return p.fields -} - -func (p *interactiveProvider) ParseForm(r *http.Request) (CheckerOptions, error) { - if p.parseErr != nil { - return nil, p.parseErr - } - if p.parseFn != nil { - return p.parseFn(r) - } - return CheckerOptions{"domain": r.FormValue("domain")}, nil -} - -func postForm(handler http.Handler, path string, values url.Values) *httptest.ResponseRecorder { - req := httptest.NewRequest("POST", path, strings.NewReader(values.Encode())) - req.Header.Set("Content-Type", "application/x-www-form-urlencoded") - rec := httptest.NewRecorder() - handler.ServeHTTP(rec, req) - return rec -} - -// minimalProvider implements only ObservationProvider. -type minimalProvider struct{ key ObservationKey } - -func (m *minimalProvider) Key() ObservationKey { return m.key } -func (m *minimalProvider) Collect(ctx context.Context, opts CheckerOptions) (any, error) { - return nil, nil -} - -func TestCheck_NotRegistered_WhenProviderLacksInterface(t *testing.T) { - p := &minimalProvider{key: "test"} - srv := NewServer(p) - defer srv.Close() - - rec := doRequest(srv.Handler(), "GET", "/check", nil, nil) - if rec.Code != http.StatusNotFound { - t.Fatalf("GET /check without CheckerInteractive = %d, want 404", rec.Code) - } -} - -func TestCheck_Form_Renders(t *testing.T) { - p := &interactiveProvider{ - testProvider: &testProvider{key: "test"}, - fields: []CheckerOptionField{ - {Id: "domain", Type: "string", Label: "Domain name", Required: true, Placeholder: "example.com"}, - {Id: "verbose", Type: "bool", Label: "Verbose", Default: true}, - {Id: "flavor", Type: "string", Choices: []string{"a", "b"}, Default: "b"}, - {Id: "hidden", Type: "string", Hide: true}, - }, - } - srv := NewServer(p) - defer srv.Close() - - rec := doRequest(srv.Handler(), "GET", "/check", nil, nil) - if rec.Code != http.StatusOK { - t.Fatalf("GET /check = %d, want 200", rec.Code) - } - body := rec.Body.String() - for _, want := range []string{ - `name="domain"`, - `placeholder="example.com"`, - `Domain name`, - `type="checkbox"`, - `name="verbose"`, - ` checked`, - ``, + } { + if !strings.Contains(body, want) { + t.Errorf("form body missing %q", want) + } + } + if strings.Contains(body, `name="hidden"`) { + t.Errorf("hidden field should not be rendered") + } +} + +func TestCheck_Submit_Success(t *testing.T) { + definition := &checker.CheckerDefinition{ + ID: "test", + Name: "Test Checker", + Rules: []checker.CheckRule{ + &dummyRule{name: "rule1", desc: "first rule"}, + }, + } + p := &interactiveProvider{ + testProvider: &testProvider{key: "test", definition: definition}, + fields: []checker.CheckerOptionField{{Id: "domain", Type: "string"}}, + } + srv := New(p) + defer srv.Close() + + rec := postForm(srv.Handler(), "/check", url.Values{"domain": {"example.com"}}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /check = %d, want 200", rec.Code) + } + body := rec.Body.String() + for _, want := range []string{ + `Test Checker`, + `Check states`, + `rule1`, + `rule1 passed`, + `badge ok`, + `Metrics`, + `m1`, + `Report`, + `Metrics") { + t.Errorf("body should not contain metrics section when no metrics reporter") + } +} + +// bareInteractiveProvider implements only the required interfaces +// (ObservationProvider, CheckerDefinitionProvider, Interactive), +// no reporters. +type bareInteractiveProvider struct { + key checker.ObservationKey + def *checker.CheckerDefinition +} + +func (b *bareInteractiveProvider) Key() checker.ObservationKey { return b.key } +func (b *bareInteractiveProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + return map[string]string{"ok": "1"}, nil +} +func (b *bareInteractiveProvider) Definition() *checker.CheckerDefinition { return b.def } +func (b *bareInteractiveProvider) RenderForm() []checker.CheckerOptionField { + return []checker.CheckerOptionField{{Id: "domain", Type: "string"}} +} +func (b *bareInteractiveProvider) ParseForm(r *http.Request) (checker.CheckerOptions, error) { + return checker.CheckerOptions{"domain": r.FormValue("domain")}, nil +} + +type siblingProvider struct { + key checker.ObservationKey + id string + entriesOpt string + gotOpts checker.CheckerOptions + payload any +} + +func (s *siblingProvider) Key() checker.ObservationKey { return s.key } +func (s *siblingProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + s.gotOpts = opts + return s.payload, nil +} +func (s *siblingProvider) Definition() *checker.CheckerDefinition { + return &checker.CheckerDefinition{ + ID: s.id, + Options: checker.CheckerOptionsDocumentation{ + RunOpts: []checker.CheckerOptionDocumentation{ + {Id: s.entriesOpt, Type: "array", AutoFill: checker.AutoFillDiscoveryEntries}, + }, + }, + } +} + +type primaryWithSibling struct { + key checker.ObservationKey + def *checker.CheckerDefinition + entries []checker.DiscoveryEntry + sibling checker.ObservationProvider +} + +func (p *primaryWithSibling) Key() checker.ObservationKey { return p.key } +func (p *primaryWithSibling) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + return map[string]string{"primary": "ok"}, nil +} +func (p *primaryWithSibling) Definition() *checker.CheckerDefinition { return p.def } +func (p *primaryWithSibling) RenderForm() []checker.CheckerOptionField { + return []checker.CheckerOptionField{{Id: "domain", Type: "string"}} +} +func (p *primaryWithSibling) ParseForm(r *http.Request) (checker.CheckerOptions, error) { + return checker.CheckerOptions{"domain": r.FormValue("domain")}, nil +} +func (p *primaryWithSibling) DiscoverEntries(data any) ([]checker.DiscoveryEntry, error) { + return p.entries, nil +} +func (p *primaryWithSibling) RelatedProviders() []checker.ObservationProvider { + return []checker.ObservationProvider{p.sibling} +} + +type relatedAssertRule struct { + key checker.ObservationKey +} + +func (r *relatedAssertRule) Name() string { return "related_assert" } +func (r *relatedAssertRule) Description() string { return "" } +func (r *relatedAssertRule) Evaluate(ctx context.Context, obs checker.ObservationGetter, opts checker.CheckerOptions) []checker.CheckState { + related, err := obs.GetRelated(ctx, r.key) + if err != nil { + return []checker.CheckState{{Status: checker.StatusError, Message: err.Error()}} + } + if len(related) == 0 { + return []checker.CheckState{{Status: checker.StatusCrit, Message: "no related observation"}} + } + return []checker.CheckState{{Status: checker.StatusOK, Message: "saw related observation"}} +} + +func TestCheck_Submit_RunsSiblingAndExposesRelated(t *testing.T) { + sibling := &siblingProvider{ + key: "sibling_key", + id: "sibling", + entriesOpt: "endpoints", + payload: map[string]string{"sibling": "ok"}, + } + entry := checker.DiscoveryEntry{Type: "fake.v1", Ref: "r1"} + primary := &primaryWithSibling{ + key: "primary_key", + def: &checker.CheckerDefinition{ + ID: "primary", + Rules: []checker.CheckRule{&relatedAssertRule{key: sibling.key}}, + }, + entries: []checker.DiscoveryEntry{entry}, + sibling: sibling, + } + + srv := New(primary) + defer srv.Close() + + rec := postForm(srv.Handler(), "/check", url.Values{"domain": {"example.com"}}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /check = %d, want 200", rec.Code) + } + body := rec.Body.String() + if !strings.Contains(body, "saw related observation") { + t.Errorf("rule did not see related observation; body:\n%s", body) + } + + got, ok := sibling.gotOpts[sibling.entriesOpt].([]checker.DiscoveryEntry) + if !ok { + t.Fatalf("sibling opts missing %q or wrong type: %#v", sibling.entriesOpt, sibling.gotOpts[sibling.entriesOpt]) + } + if len(got) != 1 || got[0].Ref != entry.Ref { + t.Errorf("sibling saw entries %v, want [%v]", got, entry) + } + + if v, _ := sibling.gotOpts["domain"].(string); v != "example.com" { + t.Errorf("sibling did not receive primary domain opt, got %q", v) + } +} + +// interactiveStatesPeekingProvider implements Interactive + HTMLReporter +// and captures the ReportContext.States() seen at GetHTMLReport time. +type interactiveStatesPeekingProvider struct { + key checker.ObservationKey + def *checker.CheckerDefinition + seen *[]checker.CheckState +} + +func (p *interactiveStatesPeekingProvider) Key() checker.ObservationKey { return p.key } +func (p *interactiveStatesPeekingProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + return map[string]string{"ok": "1"}, nil +} +func (p *interactiveStatesPeekingProvider) Definition() *checker.CheckerDefinition { return p.def } +func (p *interactiveStatesPeekingProvider) RenderForm() []checker.CheckerOptionField { + return []checker.CheckerOptionField{{Id: "domain", Type: "string"}} +} +func (p *interactiveStatesPeekingProvider) ParseForm(r *http.Request) (checker.CheckerOptions, error) { + return checker.CheckerOptions{"domain": r.FormValue("domain")}, nil +} +func (p *interactiveStatesPeekingProvider) GetHTMLReport(ctx checker.ReportContext) (string, error) { + if p.seen != nil { + *p.seen = ctx.States() + } + return "

ok

", nil +} + +// TestCheck_Submit_ThreadsStatesIntoReport verifies that CheckStates +// produced by evaluateRules during POST /check are threaded into the +// ReportContext handed to GetHTMLReport. Without this wiring, the /check +// UI can show states in its own section but the embedded report would +// have to re-derive severity/hints from Data. +func TestCheck_Submit_ThreadsStatesIntoReport(t *testing.T) { + var seen []checker.CheckState + p := &interactiveStatesPeekingProvider{ + key: "test", + def: &checker.CheckerDefinition{ + ID: "test", + Rules: []checker.CheckRule{&dummyRule{name: "rule1", desc: "first"}}, + }, + seen: &seen, + } + srv := New(p) + defer srv.Close() + + rec := postForm(srv.Handler(), "/check", url.Values{"domain": {"example.com"}}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /check = %d, want 200", rec.Code) + } + if len(seen) != 1 { + t.Fatalf("reporter saw %d states, want 1", len(seen)) + } + if seen[0].RuleName != "rule1" { + t.Errorf("state RuleName = %q, want %q", seen[0].RuleName, "rule1") + } + if seen[0].Status != checker.StatusOK { + t.Errorf("state Status = %v, want %v", seen[0].Status, checker.StatusOK) + } +} + +func TestCheck_Submit_NoSibling_LeavesRelatedEmpty(t *testing.T) { + p := &interactiveProvider{ + testProvider: &testProvider{ + key: "test", + definition: &checker.CheckerDefinition{ + ID: "test", + Rules: []checker.CheckRule{&relatedAssertRule{key: "other"}}, + }, + }, + fields: []checker.CheckerOptionField{{Id: "domain", Type: "string"}}, + } + srv := New(p) + defer srv.Close() + + rec := postForm(srv.Handler(), "/check", url.Values{"domain": {"example.com"}}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /check = %d, want 200", rec.Code) + } + body := rec.Body.String() + if !strings.Contains(body, "no related observation") { + t.Errorf("rule should have seen no related observation; body:\n%s", body) + } +} diff --git a/checker/server.go b/checker/server/server.go similarity index 66% rename from checker/server.go rename to checker/server/server.go index 1c25e31..763a600 100644 --- a/checker/server.go +++ b/checker/server/server.go @@ -12,7 +12,11 @@ // See the License for the specific language governing permissions and // limitations under the License. -package checker +// 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. +package server import ( "context" @@ -22,11 +26,16 @@ import ( "log" "math" "net/http" + "os" + "os/signal" "runtime" "strings" "sync" "sync/atomic" + "syscall" "time" + + "git.happydns.org/checker-sdk-go/checker" ) // maxRequestBodySize is the maximum allowed size for incoming request bodies (1 MB). @@ -37,6 +46,10 @@ const maxRequestBodySize = 1 << 20 // 5 seconds matches the Unix kernel's loadavg cadence. const loadSampleInterval = 5 * time.Second +// shutdownTimeout bounds how long ListenAndServe waits for in-flight +// requests to drain after receiving SIGINT or SIGTERM. +const shutdownTimeout = 10 * time.Second + // EWMA smoothing factors for 1, 5, and 15-minute windows sampled every // loadSampleInterval. Derived as 1 - exp(-interval/window) so that the // steady-state response to a constant InFlight of N converges to N. @@ -58,21 +71,21 @@ func updateLoadAvg(prev [3]float64, sample float64) [3]float64 { // Server is a generic HTTP server for external checkers. // It always exposes /health and /collect. If the provider implements -// CheckerDefinitionProvider, it also exposes /definition and /evaluate. -// If the provider implements CheckerHTMLReporter or CheckerMetricsReporter, -// it also exposes /report. If the provider implements CheckerInteractive, +// 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). type Server struct { - provider ObservationProvider - definition *CheckerDefinition - interactive CheckerInteractive + provider checker.ObservationProvider + definition *checker.CheckerDefinition + interactive Interactive mux *http.ServeMux - // startTime is captured in NewServer and used to compute uptime. + // startTime is captured in New and used to compute uptime. startTime time.Time // inFlight counts work requests (/collect, /evaluate, /report) currently @@ -97,13 +110,13 @@ type Server struct { closeOnce sync.Once } -// NewServer creates a new checker HTTP server backed by the given provider. +// New creates a new checker HTTP server backed by the given provider. // Additional endpoints are registered based on optional interfaces the provider implements. // -// NewServer also starts a background goroutine that samples the in-flight +// 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 NewServer(provider ObservationProvider) *Server { +func New(provider checker.ObservationProvider) *Server { ctx, cancel := context.WithCancel(context.Background()) s := &Server{ provider: provider, @@ -115,7 +128,7 @@ func NewServer(provider ObservationProvider) *Server { s.mux.HandleFunc("GET /health", s.handleHealth) s.mux.Handle("POST /collect", s.TrackWork(http.HandlerFunc(s.handleCollect))) - if dp, ok := provider.(CheckerDefinitionProvider); ok { + if dp, ok := provider.(checker.CheckerDefinitionProvider); ok { if def := dp.Definition(); def != nil { s.definition = def s.definition.BuildRulesInfo() @@ -124,13 +137,13 @@ func NewServer(provider ObservationProvider) *Server { } } - if _, ok := provider.(CheckerHTMLReporter); ok { + if _, ok := provider.(checker.CheckerHTMLReporter); ok { s.mux.Handle("POST /report", s.TrackWork(http.HandlerFunc(s.handleReport))) - } else if _, ok := provider.(CheckerMetricsReporter); ok { + } else if _, ok := provider.(checker.CheckerMetricsReporter); ok { s.mux.Handle("POST /report", s.TrackWork(http.HandlerFunc(s.handleReport))) } - if ip, ok := provider.(CheckerInteractive); ok { + if ip, ok := provider.(Interactive); ok { s.interactive = ip s.mux.HandleFunc("GET /check", s.handleCheckForm) s.mux.Handle("POST /check", s.TrackWork(http.HandlerFunc(s.handleCheckSubmit))) @@ -159,19 +172,70 @@ func (s *Server) HandleFunc(pattern string, handler func(http.ResponseWriter, *h s.mux.HandleFunc(pattern, handler) } -// ListenAndServe starts the HTTP server on the given address. +// ListenAndServe starts the HTTP server on the given address and blocks +// until the server stops. // -// ListenAndServe does not stop the background load-average sampler on return; -// call Close to stop it. This is not required for process-scoped usage but is -// recommended for tests and embedded lifecycles. +// 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. func (s *Server) ListenAndServe(addr string) error { + if *healthcheckMode { + if err := runHealthcheck(addr); err != nil { + fmt.Fprintln(os.Stderr, "healthcheck failed:", err) + os.Exit(1) + } + os.Exit(0) + } + + srv := &http.Server{Addr: addr, Handler: requestLogger(s.mux)} + + sigCh := make(chan os.Signal, 1) + signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM) + defer signal.Stop(sigCh) + + shutdownErr := make(chan error, 1) + go func() { + sig, ok := <-sigCh + if !ok { + shutdownErr <- nil + return + } + log.Printf("checker received %s, shutting down (timeout %s)", sig, shutdownTimeout) + ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout) + defer cancel() + shutdownErr <- srv.Shutdown(ctx) + }() + log.Printf("checker listening on %s", addr) - return http.ListenAndServe(addr, requestLogger(s.mux)) + err := srv.ListenAndServe() + signal.Stop(sigCh) + close(sigCh) + + if err == http.ErrServerClosed { + if sErr := <-shutdownErr; sErr != nil { + err = sErr + } else { + err = nil + } + } + + if cErr := s.Close(); cErr != nil && err == nil { + err = cErr + } + return err } // 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. +// any underlying http.Server, callers own that lifecycle. func (s *Server) Close() error { s.closeOnce.Do(func() { s.cancelSampler() @@ -238,7 +302,7 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) { for i := range load { load[i] = math.Float64frombits(s.loadBits[i].Load()) } - writeJSON(w, http.StatusOK, HealthResponse{ + writeJSON(w, http.StatusOK, checker.HealthResponse{ Status: "ok", Uptime: time.Since(s.startTime).Seconds(), NumCPU: runtime.NumCPU(), @@ -253,9 +317,9 @@ func (s *Server) handleDefinition(w http.ResponseWriter, r *http.Request) { } func (s *Server) handleCollect(w http.ResponseWriter, r *http.Request) { - var req ExternalCollectRequest + var req checker.ExternalCollectRequest if err := json.NewDecoder(io.LimitReader(r.Body, maxRequestBodySize)).Decode(&req); err != nil { - writeJSON(w, http.StatusBadRequest, ExternalCollectResponse{ + writeJSON(w, http.StatusBadRequest, checker.ExternalCollectResponse{ Error: fmt.Sprintf("invalid request body: %v", err), }) return @@ -263,7 +327,7 @@ func (s *Server) handleCollect(w http.ResponseWriter, r *http.Request) { data, err := s.provider.Collect(r.Context(), req.Options) if err != nil { - writeJSON(w, http.StatusInternalServerError, ExternalCollectResponse{ + writeJSON(w, http.StatusInternalServerError, checker.ExternalCollectResponse{ Error: err.Error(), }) return @@ -271,18 +335,18 @@ func (s *Server) handleCollect(w http.ResponseWriter, r *http.Request) { raw, err := json.Marshal(data) if err != nil { - writeJSON(w, http.StatusInternalServerError, ExternalCollectResponse{ + writeJSON(w, http.StatusInternalServerError, checker.ExternalCollectResponse{ Error: fmt.Sprintf("failed to marshal result: %v", err), }) return } - resp := ExternalCollectResponse{Data: json.RawMessage(raw)} + resp := checker.ExternalCollectResponse{Data: json.RawMessage(raw)} // Harvest discovery entries from the native Go value, before it goes // out of scope. No re-parse; DiscoverEntries operates on the same // object that was just marshaled above. - if dp, ok := s.provider.(DiscoveryPublisher); ok { + if dp, ok := s.provider.(checker.DiscoveryPublisher); ok { entries, derr := dp.DiscoverEntries(data) if derr != nil { log.Printf("DiscoverEntries failed: %v", derr) @@ -296,8 +360,8 @@ func (s *Server) handleCollect(w http.ResponseWriter, r *http.Request) { // evaluateRules runs all definition rules against obs/opts, skipping any rule // whose name maps to false in enabledRules (nil means run all). -func (s *Server) evaluateRules(ctx context.Context, obs ObservationGetter, opts CheckerOptions, enabledRules map[string]bool) []CheckState { - var states []CheckState +func (s *Server) evaluateRules(ctx context.Context, obs checker.ObservationGetter, opts checker.CheckerOptions, enabledRules map[string]bool) []checker.CheckState { + var states []checker.CheckState for _, rule := range s.definition.Rules { if len(enabledRules) > 0 { if enabled, ok := enabledRules[rule.Name()]; ok && !enabled { @@ -306,8 +370,8 @@ func (s *Server) evaluateRules(ctx context.Context, obs ObservationGetter, opts } ruleStates := rule.Evaluate(ctx, obs, opts) if len(ruleStates) == 0 { - ruleStates = []CheckState{{ - Status: StatusUnknown, + ruleStates = []checker.CheckState{{ + Status: checker.StatusUnknown, Message: fmt.Sprintf("rule %q returned no state", rule.Name()), }} } @@ -320,9 +384,9 @@ func (s *Server) evaluateRules(ctx context.Context, obs ObservationGetter, opts } func (s *Server) handleEvaluate(w http.ResponseWriter, r *http.Request) { - var req ExternalEvaluateRequest + var req checker.ExternalEvaluateRequest if err := json.NewDecoder(io.LimitReader(r.Body, maxRequestBodySize)).Decode(&req); err != nil { - writeJSON(w, http.StatusBadRequest, ExternalEvaluateResponse{ + writeJSON(w, http.StatusBadRequest, checker.ExternalEvaluateResponse{ Error: fmt.Sprintf("invalid request body: %v", err), }) return @@ -330,11 +394,11 @@ func (s *Server) handleEvaluate(w http.ResponseWriter, r *http.Request) { obs := &mapObservationGetter{data: req.Observations} states := s.evaluateRules(r.Context(), obs, req.Options, req.EnabledRules) - writeJSON(w, http.StatusOK, ExternalEvaluateResponse{States: states}) + writeJSON(w, http.StatusOK, checker.ExternalEvaluateResponse{States: states}) } func (s *Server) handleReport(w http.ResponseWriter, r *http.Request) { - var req ExternalReportRequest + var req checker.ExternalReportRequest if err := json.NewDecoder(io.LimitReader(r.Body, maxRequestBodySize)).Decode(&req); err != nil { writeJSON(w, http.StatusBadRequest, map[string]string{ "error": fmt.Sprintf("invalid request body: %v", err), @@ -345,13 +409,13 @@ func (s *Server) handleReport(w http.ResponseWriter, r *http.Request) { accept := r.Header.Get("Accept") if strings.Contains(accept, "text/html") { - reporter, ok := s.provider.(CheckerHTMLReporter) + reporter, ok := s.provider.(checker.CheckerHTMLReporter) if !ok { http.Error(w, "this checker does not support HTML reports", http.StatusNotImplemented) return } - html, err := reporter.GetHTMLReport(NewReportContext(req.Data, req.Related)) + html, err := reporter.GetHTMLReport(checker.NewReportContext(req.Data, req.Related, req.States)) if err != nil { http.Error(w, fmt.Sprintf("failed to generate HTML report: %v", err), http.StatusInternalServerError) return @@ -363,13 +427,13 @@ func (s *Server) handleReport(w http.ResponseWriter, r *http.Request) { } // Default: JSON metrics. - reporter, ok := s.provider.(CheckerMetricsReporter) + reporter, ok := s.provider.(checker.CheckerMetricsReporter) if !ok { http.Error(w, "this checker does not support metrics reports", http.StatusNotImplemented) return } - metrics, err := reporter.ExtractMetrics(NewReportContext(req.Data, req.Related), time.Now()) + metrics, err := reporter.ExtractMetrics(checker.NewReportContext(req.Data, req.Related, req.States), time.Now()) if err != nil { writeJSON(w, http.StatusInternalServerError, map[string]string{ "error": fmt.Sprintf("failed to extract metrics: %v", err), @@ -380,12 +444,16 @@ func (s *Server) handleReport(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, metrics) } -// mapObservationGetter implements ObservationGetter backed by a static map. +// mapObservationGetter implements checker.ObservationGetter backed by static maps. +// Both fields are optional: Get reads from data, GetRelated reads from +// related. Leaving related nil preserves the pre-existing "no lineage" +// behavior used by the remote /evaluate path. type mapObservationGetter struct { - data map[ObservationKey]json.RawMessage + data map[checker.ObservationKey]json.RawMessage + related map[checker.ObservationKey][]checker.RelatedObservation } -func (g *mapObservationGetter) Get(ctx context.Context, key ObservationKey, dest any) error { +func (g *mapObservationGetter) Get(ctx context.Context, key checker.ObservationKey, dest any) error { raw, ok := g.data[key] if !ok { return fmt.Errorf("observation %q not available", key) @@ -393,13 +461,13 @@ func (g *mapObservationGetter) Get(ctx context.Context, key ObservationKey, dest return json.Unmarshal(raw, dest) } -// GetRelated always returns nil in the remote /evaluate path: the host that -// invokes /evaluate does not (currently) carry cross-checker related data in -// ExternalEvaluateRequest. Consumers that need related observations must run -// evaluation locally with a host-side ObservationContext that resolves -// lineage. -func (g *mapObservationGetter) GetRelated(ctx context.Context, key ObservationKey) ([]RelatedObservation, error) { - return nil, nil +// GetRelated returns the pre-resolved related observations for key, or nil +// when none were seeded. The remote /evaluate path leaves related nil +// because ExternalEvaluateRequest does not currently carry cross-checker +// lineage; the interactive /check path can seed it from sibling providers +// declared via Siblings. +func (g *mapObservationGetter) GetRelated(ctx context.Context, key checker.ObservationKey) ([]checker.RelatedObservation, error) { + return g.related[key], nil } func writeJSON(w http.ResponseWriter, status int, v any) { diff --git a/checker/server_test.go b/checker/server/server_test.go similarity index 60% rename from checker/server_test.go rename to checker/server/server_test.go index 7b07e13..9e0adc4 100644 --- a/checker/server_test.go +++ b/checker/server/server_test.go @@ -12,7 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -package checker +package server import ( "bytes" @@ -24,37 +24,39 @@ import ( "sync" "testing" "time" + + "git.happydns.org/checker-sdk-go/checker" ) // --- test doubles --- type testProvider struct { - key ObservationKey - collectFn func(ctx context.Context, opts CheckerOptions) (any, error) - definition *CheckerDefinition + key checker.ObservationKey + collectFn func(ctx context.Context, opts checker.CheckerOptions) (any, error) + definition *checker.CheckerDefinition htmlFn func(raw json.RawMessage) (string, error) - metricsFn func(raw json.RawMessage, t time.Time) ([]CheckMetric, error) + metricsFn func(raw json.RawMessage, t time.Time) ([]checker.CheckMetric, error) } -func (p *testProvider) Key() ObservationKey { return p.key } -func (p *testProvider) Collect(ctx context.Context, opts CheckerOptions) (any, error) { +func (p *testProvider) Key() checker.ObservationKey { return p.key } +func (p *testProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { if p.collectFn != nil { return p.collectFn(ctx, opts) } return map[string]string{"result": "ok"}, nil } -func (p *testProvider) Definition() *CheckerDefinition { return p.definition } -func (p *testProvider) GetHTMLReport(ctx ReportContext) (string, error) { +func (p *testProvider) Definition() *checker.CheckerDefinition { return p.definition } +func (p *testProvider) GetHTMLReport(ctx checker.ReportContext) (string, error) { if p.htmlFn != nil { return p.htmlFn(ctx.Data()) } return "

report

", nil } -func (p *testProvider) ExtractMetrics(ctx ReportContext, t time.Time) ([]CheckMetric, error) { +func (p *testProvider) ExtractMetrics(ctx checker.ReportContext, t time.Time) ([]checker.CheckMetric, error) { if p.metricsFn != nil { return p.metricsFn(ctx.Data(), t) } - return []CheckMetric{{Name: "m1", Value: 1.0, Timestamp: t}}, nil + return []checker.CheckMetric{{Name: "m1", Value: 1.0, Timestamp: t}}, nil } // dummyRule is a minimal CheckRule for testing evaluate. @@ -65,8 +67,8 @@ type dummyRule struct { func (r *dummyRule) Name() string { return r.name } func (r *dummyRule) Description() string { return r.desc } -func (r *dummyRule) Evaluate(ctx context.Context, obs ObservationGetter, opts CheckerOptions) []CheckState { - return []CheckState{{Status: StatusOK, Message: r.name + " passed"}} +func (r *dummyRule) Evaluate(ctx context.Context, obs checker.ObservationGetter, opts checker.CheckerOptions) []checker.CheckState { + return []checker.CheckState{{Status: checker.StatusOK, Message: r.name + " passed"}} } // codedRule emits a CheckState with a pre-set Code, to verify the server @@ -77,14 +79,25 @@ type codedRule struct { func (r *codedRule) Name() string { return r.name } func (r *codedRule) Description() string { return "" } -func (r *codedRule) Evaluate(ctx context.Context, obs ObservationGetter, opts CheckerOptions) []CheckState { - return []CheckState{{Status: StatusWarn, Code: r.code, Message: "coded finding"}} +func (r *codedRule) Evaluate(ctx context.Context, obs checker.ObservationGetter, opts checker.CheckerOptions) []checker.CheckState { + return []checker.CheckState{{Status: checker.StatusWarn, Code: r.code, Message: "coded finding"}} +} + +// stubProvider is a minimal ObservationProvider that does not implement +// CheckerDefinitionProvider, used to verify conditional endpoint registration. +type stubProvider struct { + key checker.ObservationKey +} + +func (s stubProvider) Key() checker.ObservationKey { return s.key } +func (s stubProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + return nil, nil } // --- helpers --- func newTestServer(p *testProvider) *Server { - return NewServer(p) + return New(p) } func doRequest(handler http.Handler, method, path string, body any, headers map[string]string) *httptest.ResponseRecorder { @@ -107,14 +120,14 @@ func doRequest(handler http.Handler, method, path string, body any, headers map[ // --- tests --- func TestServer_Health(t *testing.T) { - p := &testProvider{key: "test", definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}} + p := &testProvider{key: "test", definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}} srv := newTestServer(p) defer srv.Close() rec := doRequest(srv.Handler(), "GET", "/health", nil, nil) if rec.Code != http.StatusOK { t.Fatalf("GET /health = %d, want %d", rec.Code, http.StatusOK) } - var resp HealthResponse + var resp checker.HealthResponse if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil { t.Fatalf("decode /health: %v", err) } @@ -143,8 +156,8 @@ func TestServer_Health_TracksInFlight(t *testing.T) { var collectEntered sync.WaitGroup p := &testProvider{ key: "test", - definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}, - collectFn: func(ctx context.Context, opts CheckerOptions) (any, error) { + definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}, + collectFn: func(ctx context.Context, opts checker.CheckerOptions) (any, error) { collectEntered.Done() <-release return map[string]string{"ok": "1"}, nil @@ -161,7 +174,7 @@ func TestServer_Health_TracksInFlight(t *testing.T) { for i := 0; i < n; i++ { go func() { defer clientsDone.Done() - doRequest(handler, "POST", "/collect", ExternalCollectRequest{Key: "test"}, nil) + doRequest(handler, "POST", "/collect", checker.ExternalCollectRequest{Key: "test"}, nil) }() } @@ -170,7 +183,7 @@ func TestServer_Health_TracksInFlight(t *testing.T) { // Record /health mid-flight. Also hammer it to verify /health polls // do not inflate InFlight or TotalRequests. - var mid HealthResponse + var mid checker.HealthResponse for i := 0; i < 5; i++ { rec := doRequest(handler, "GET", "/health", nil, nil) if rec.Code != http.StatusOK { @@ -192,7 +205,7 @@ func TestServer_Health_TracksInFlight(t *testing.T) { clientsDone.Wait() rec := doRequest(handler, "GET", "/health", nil, nil) - var after HealthResponse + var after checker.HealthResponse if err := json.NewDecoder(rec.Body).Decode(&after); err != nil { t.Fatalf("decode /health: %v", err) } @@ -237,7 +250,7 @@ func TestUpdateLoadAvg(t *testing.T) { } func TestServer_Close_Idempotent(t *testing.T) { - p := &testProvider{key: "test", definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}} + p := &testProvider{key: "test", definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}} srv := newTestServer(p) done := make(chan error, 2) go func() { done <- srv.Close() }() @@ -257,20 +270,20 @@ func TestServer_Close_Idempotent(t *testing.T) { func TestServer_Collect_Success(t *testing.T) { p := &testProvider{ key: "test", - definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}, - collectFn: func(ctx context.Context, opts CheckerOptions) (any, error) { + definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}, + collectFn: func(ctx context.Context, opts checker.CheckerOptions) (any, error) { return map[string]int{"count": 42}, nil }, } srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/collect", ExternalCollectRequest{ + rec := doRequest(srv.Handler(), "POST", "/collect", checker.ExternalCollectRequest{ Key: "test", - Options: CheckerOptions{"a": "b"}, + Options: checker.CheckerOptions{"a": "b"}, }, nil) if rec.Code != http.StatusOK { t.Fatalf("POST /collect = %d, want %d", rec.Code, http.StatusOK) } - var resp ExternalCollectResponse + var resp checker.ExternalCollectResponse json.NewDecoder(rec.Body).Decode(&resp) if resp.Error != "" { t.Errorf("POST /collect error = %q, want empty", resp.Error) @@ -283,17 +296,17 @@ func TestServer_Collect_Success(t *testing.T) { func TestServer_Collect_ProviderError(t *testing.T) { p := &testProvider{ key: "test", - definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}, - collectFn: func(ctx context.Context, opts CheckerOptions) (any, error) { + definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}, + collectFn: func(ctx context.Context, opts checker.CheckerOptions) (any, error) { return nil, errors.New("provider failed") }, } srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/collect", ExternalCollectRequest{Key: "test"}, nil) + rec := doRequest(srv.Handler(), "POST", "/collect", checker.ExternalCollectRequest{Key: "test"}, nil) if rec.Code != http.StatusInternalServerError { t.Fatalf("POST /collect = %d, want %d", rec.Code, http.StatusInternalServerError) } - var resp ExternalCollectResponse + var resp checker.ExternalCollectResponse json.NewDecoder(rec.Body).Decode(&resp) if resp.Error == "" { t.Error("expected error in response, got empty") @@ -301,7 +314,7 @@ func TestServer_Collect_ProviderError(t *testing.T) { } func TestServer_Collect_BadBody(t *testing.T) { - p := &testProvider{key: "test", definition: &CheckerDefinition{ID: "test", Rules: []CheckRule{}}} + p := &testProvider{key: "test", definition: &checker.CheckerDefinition{ID: "test", Rules: []checker.CheckRule{}}} srv := newTestServer(p) req := httptest.NewRequest("POST", "/collect", bytes.NewBufferString("{invalid")) rec := httptest.NewRecorder() @@ -312,10 +325,10 @@ func TestServer_Collect_BadBody(t *testing.T) { } func TestServer_Definition(t *testing.T) { - def := &CheckerDefinition{ + def := &checker.CheckerDefinition{ ID: "test-checker", Name: "Test Checker", - Rules: []CheckRule{ + Rules: []checker.CheckRule{ &dummyRule{name: "rule1", desc: "first rule"}, }, } @@ -325,7 +338,7 @@ func TestServer_Definition(t *testing.T) { if rec.Code != http.StatusOK { t.Fatalf("GET /definition = %d, want %d", rec.Code, http.StatusOK) } - var got CheckerDefinition + var got checker.CheckerDefinition json.NewDecoder(rec.Body).Decode(&got) if got.ID != "test-checker" { t.Errorf("definition ID = %q, want \"test-checker\"", got.ID) @@ -336,10 +349,10 @@ func TestServer_Definition(t *testing.T) { } func TestServer_Evaluate(t *testing.T) { - def := &CheckerDefinition{ + def := &checker.CheckerDefinition{ ID: "test-checker", Name: "Test Checker", - Rules: []CheckRule{ + Rules: []checker.CheckRule{ &dummyRule{name: "rule1", desc: "first rule"}, &dummyRule{name: "rule2", desc: "second rule"}, }, @@ -347,16 +360,16 @@ func TestServer_Evaluate(t *testing.T) { p := &testProvider{key: "test", definition: def} srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/evaluate", ExternalEvaluateRequest{ - Observations: map[ObservationKey]json.RawMessage{ + rec := doRequest(srv.Handler(), "POST", "/evaluate", checker.ExternalEvaluateRequest{ + Observations: map[checker.ObservationKey]json.RawMessage{ "test": json.RawMessage(`{"count":42}`), }, - Options: CheckerOptions{}, + Options: checker.CheckerOptions{}, }, nil) if rec.Code != http.StatusOK { t.Fatalf("POST /evaluate = %d, want %d", rec.Code, http.StatusOK) } - var resp ExternalEvaluateResponse + var resp checker.ExternalEvaluateResponse json.NewDecoder(rec.Body).Decode(&resp) if len(resp.States) != 2 { t.Fatalf("evaluate states = %d, want 2", len(resp.States)) @@ -370,9 +383,9 @@ func TestServer_Evaluate(t *testing.T) { } func TestServer_Evaluate_DisabledRule(t *testing.T) { - def := &CheckerDefinition{ + def := &checker.CheckerDefinition{ ID: "test-checker", - Rules: []CheckRule{ + Rules: []checker.CheckRule{ &dummyRule{name: "rule1", desc: "first"}, &dummyRule{name: "rule2", desc: "second"}, }, @@ -380,8 +393,8 @@ func TestServer_Evaluate_DisabledRule(t *testing.T) { p := &testProvider{key: "test", definition: def} srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/evaluate", ExternalEvaluateRequest{ - Observations: map[ObservationKey]json.RawMessage{ + rec := doRequest(srv.Handler(), "POST", "/evaluate", checker.ExternalEvaluateRequest{ + Observations: map[checker.ObservationKey]json.RawMessage{ "test": json.RawMessage(`{}`), }, EnabledRules: map[string]bool{"rule1": false}, @@ -389,7 +402,7 @@ func TestServer_Evaluate_DisabledRule(t *testing.T) { if rec.Code != http.StatusOK { t.Fatalf("POST /evaluate = %d, want %d", rec.Code, http.StatusOK) } - var resp ExternalEvaluateResponse + var resp checker.ExternalEvaluateResponse json.NewDecoder(rec.Body).Decode(&resp) if len(resp.States) != 1 { t.Fatalf("evaluate with disabled rule: states = %d, want 1", len(resp.States)) @@ -400,22 +413,22 @@ func TestServer_Evaluate_DisabledRule(t *testing.T) { } func TestServer_Evaluate_RulePreservesCode(t *testing.T) { - def := &CheckerDefinition{ + def := &checker.CheckerDefinition{ ID: "test-checker", - Rules: []CheckRule{ + Rules: []checker.CheckRule{ &codedRule{name: "ruleA", code: "too_many_lookups"}, }, } p := &testProvider{key: "test", definition: def} srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/evaluate", ExternalEvaluateRequest{ - Observations: map[ObservationKey]json.RawMessage{"test": json.RawMessage(`{}`)}, + rec := doRequest(srv.Handler(), "POST", "/evaluate", checker.ExternalEvaluateRequest{ + Observations: map[checker.ObservationKey]json.RawMessage{"test": json.RawMessage(`{}`)}, }, nil) if rec.Code != http.StatusOK { t.Fatalf("POST /evaluate = %d, want %d", rec.Code, http.StatusOK) } - var resp ExternalEvaluateResponse + var resp checker.ExternalEvaluateResponse json.NewDecoder(rec.Body).Decode(&resp) if len(resp.States) != 1 { t.Fatalf("states = %d, want 1", len(resp.States)) @@ -430,14 +443,14 @@ func TestServer_Evaluate_RulePreservesCode(t *testing.T) { func TestServer_Report_HTML(t *testing.T) { p := &testProvider{ - key: "test", - definition: &CheckerDefinition{ID: "test-checker", Rules: []CheckRule{}}, + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, htmlFn: func(raw json.RawMessage) (string, error) { return "

hello

", nil }, } srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/report", ExternalReportRequest{ + rec := doRequest(srv.Handler(), "POST", "/report", checker.ExternalReportRequest{ Key: "test", Data: json.RawMessage(`{}`), }, map[string]string{"Accept": "text/html"}) @@ -454,18 +467,18 @@ func TestServer_Report_HTML(t *testing.T) { func TestServer_Report_Metrics(t *testing.T) { p := &testProvider{ - key: "test", - definition: &CheckerDefinition{ID: "test-checker", Rules: []CheckRule{}}, + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, } srv := newTestServer(p) - rec := doRequest(srv.Handler(), "POST", "/report", ExternalReportRequest{ + rec := doRequest(srv.Handler(), "POST", "/report", checker.ExternalReportRequest{ Key: "test", Data: json.RawMessage(`{}`), }, map[string]string{"Accept": "application/json"}) if rec.Code != http.StatusOK { t.Fatalf("POST /report metrics = %d, want %d", rec.Code, http.StatusOK) } - var metrics []CheckMetric + var metrics []checker.CheckMetric json.NewDecoder(rec.Body).Decode(&metrics) if len(metrics) != 1 { t.Errorf("metrics count = %d, want 1", len(metrics)) @@ -476,25 +489,25 @@ func TestServer_Report_Metrics(t *testing.T) { // ExternalReportRequest.Related through to the provider's ReportContext, // the fix for the "remote checkers can't see related observations" gap. func TestServer_Report_Related(t *testing.T) { - var gotRelated []RelatedObservation + var gotRelated []checker.RelatedObservation p := &testProvider{ - key: "test", - definition: &CheckerDefinition{ID: "test-checker", Rules: []CheckRule{}}, + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, } // Replace htmlFn with one that peeks at a related key. We can't do that // directly through testProvider's htmlFn (which only sees raw), so // bind to GetHTMLReport via an inline wrapper: use a per-test provider // that captures the ReportContext before delegating to the template. - srv := NewServer(&relatedPeekingProvider{ + srv := New(&relatedPeekingProvider{ base: p, target: &gotRelated, }) defer srv.Close() - req := ExternalReportRequest{ + req := checker.ExternalReportRequest{ Key: "test", Data: json.RawMessage(`{}`), - Related: map[ObservationKey][]RelatedObservation{ + Related: map[checker.ObservationKey][]checker.RelatedObservation{ "tls_probes": { {CheckerID: "tls", Key: "tls_probes", Data: json.RawMessage(`{"ok":true}`), Ref: "ep-1"}, }, @@ -516,23 +529,124 @@ func TestServer_Report_Related(t *testing.T) { // Related("tls_probes") slice observed at GetHTMLReport time into target. type relatedPeekingProvider struct { base *testProvider - target *[]RelatedObservation + target *[]checker.RelatedObservation } -func (p *relatedPeekingProvider) Key() ObservationKey { return p.base.Key() } -func (p *relatedPeekingProvider) Collect(ctx context.Context, opts CheckerOptions) (any, error) { +func (p *relatedPeekingProvider) Key() checker.ObservationKey { return p.base.Key() } +func (p *relatedPeekingProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { return p.base.Collect(ctx, opts) } -func (p *relatedPeekingProvider) Definition() *CheckerDefinition { return p.base.definition } -func (p *relatedPeekingProvider) GetHTMLReport(ctx ReportContext) (string, error) { +func (p *relatedPeekingProvider) Definition() *checker.CheckerDefinition { return p.base.definition } +func (p *relatedPeekingProvider) GetHTMLReport(ctx checker.ReportContext) (string, error) { *p.target = ctx.Related("tls_probes") return "

ok

", nil } +// statesPeekingProvider captures the ReportContext's States slice at +// GetHTMLReport / ExtractMetrics time. +type statesPeekingProvider struct { + base *testProvider + htmlSeen *[]checker.CheckState + metricSeen *[]checker.CheckState +} + +func (p *statesPeekingProvider) Key() checker.ObservationKey { return p.base.Key() } +func (p *statesPeekingProvider) Collect(ctx context.Context, opts checker.CheckerOptions) (any, error) { + return p.base.Collect(ctx, opts) +} +func (p *statesPeekingProvider) Definition() *checker.CheckerDefinition { return p.base.definition } +func (p *statesPeekingProvider) GetHTMLReport(ctx checker.ReportContext) (string, error) { + if p.htmlSeen != nil { + *p.htmlSeen = ctx.States() + } + return "

ok

", nil +} +func (p *statesPeekingProvider) ExtractMetrics(ctx checker.ReportContext, t time.Time) ([]checker.CheckMetric, error) { + if p.metricSeen != nil { + *p.metricSeen = ctx.States() + } + return []checker.CheckMetric{{Name: "m1", Value: 1.0, Timestamp: t}}, nil +} + +// TestServer_Report_States_HTML verifies ExternalReportRequest.States is +// threaded into the ReportContext seen by the HTML reporter. +func TestServer_Report_States_HTML(t *testing.T) { + var seen []checker.CheckState + base := &testProvider{ + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, + } + srv := New(&statesPeekingProvider{base: base, htmlSeen: &seen}) + defer srv.Close() + + states := []checker.CheckState{ + {Status: checker.StatusCrit, Message: "broken", RuleName: "r1", Code: "bad", Subject: "host.example"}, + } + req := checker.ExternalReportRequest{ + Key: "test", + Data: json.RawMessage(`{}`), + States: states, + } + rec := doRequest(srv.Handler(), "POST", "/report", req, map[string]string{"Accept": "text/html"}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /report = %d, want 200", rec.Code) + } + if len(seen) != 1 || seen[0].RuleName != "r1" || seen[0].Code != "bad" || seen[0].Subject != "host.example" { + t.Errorf("reporter saw states = %+v, want single state {RuleName:r1, Code:bad, Subject:host.example}", seen) + } +} + +// TestServer_Report_States_Metrics verifies the States passthrough on the +// metrics path as well. +func TestServer_Report_States_Metrics(t *testing.T) { + var seen []checker.CheckState + base := &testProvider{ + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, + } + srv := New(&statesPeekingProvider{base: base, metricSeen: &seen}) + defer srv.Close() + + req := checker.ExternalReportRequest{ + Key: "test", + Data: json.RawMessage(`{}`), + States: []checker.CheckState{{Status: checker.StatusWarn, RuleName: "r1"}}, + } + rec := doRequest(srv.Handler(), "POST", "/report", req, map[string]string{"Accept": "application/json"}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /report = %d, want 200", rec.Code) + } + if len(seen) != 1 || seen[0].RuleName != "r1" { + t.Errorf("reporter saw states = %+v, want single state with RuleName=r1", seen) + } +} + +// TestServer_Report_States_Absent verifies that omitting States in the +// request yields a nil States() slice on the reporter side (graceful +// degradation for hosts that don't thread evaluate→report yet). +func TestServer_Report_States_Absent(t *testing.T) { + seen := []checker.CheckState{{Status: checker.StatusOK}} // non-nil sentinel + base := &testProvider{ + key: "test", + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, + } + srv := New(&statesPeekingProvider{base: base, htmlSeen: &seen}) + defer srv.Close() + + req := checker.ExternalReportRequest{Key: "test", Data: json.RawMessage(`{}`)} + rec := doRequest(srv.Handler(), "POST", "/report", req, map[string]string{"Accept": "text/html"}) + if rec.Code != http.StatusOK { + t.Fatalf("POST /report = %d, want 200", rec.Code) + } + if seen != nil { + t.Errorf("States() = %+v, want nil when ExternalReportRequest.States is absent", seen) + } +} + func TestServer_Report_BadBody(t *testing.T) { p := &testProvider{ key: "test", - definition: &CheckerDefinition{ID: "test-checker", Rules: []CheckRule{}}, + definition: &checker.CheckerDefinition{ID: "test-checker", Rules: []checker.CheckRule{}}, } srv := newTestServer(p) req := httptest.NewRequest("POST", "/report", bytes.NewBufferString("{bad")) @@ -546,7 +660,7 @@ func TestServer_Report_BadBody(t *testing.T) { func TestServer_NoDefinition_NoEvaluateEndpoint(t *testing.T) { // A provider that does NOT implement CheckerDefinitionProvider p := &stubProvider{key: "basic"} - srv := NewServer(p) + srv := New(p) rec := doRequest(srv.Handler(), "POST", "/evaluate", nil, nil) // Should 404 or 405 since /evaluate is not registered if rec.Code == http.StatusOK { diff --git a/checker/types.go b/checker/types.go index c218dbb..7256766 100644 --- a/checker/types.go +++ b/checker/types.go @@ -298,32 +298,40 @@ type CheckAggregator interface { Aggregate(states []CheckState) CheckState } -// ReportContext carries both the primary observation payload and any -// observations produced by other checkers that cover the same discovery -// entries. Hosts build a ReportContext and hand it to reporter methods. +// ReportContext carries the primary observation payload, any observations +// produced by other checkers that cover the same discovery entries, and the +// CheckStates produced by this checker's rules for the same observation. +// Hosts build a ReportContext and hand it to reporter methods. // -// The method set is deliberately tiny: a single primary payload (Data) and -// a query for related observations by key (Related). Hosts return nil from -// Related when there is nothing to relate; reporters must tolerate that. +// Reporters use States() to render rule-driven sections (for example a +// "fix these first" list) without re-deriving severity or hints from the +// raw payload. Hosts that have not yet threaded rule output into the +// report pipeline return nil; reporters must treat a nil or empty slice +// as "not provided" and fall back to a data-only rendering. The same +// nil-tolerance applies to Related(key). type ReportContext interface { Data() json.RawMessage Related(key ObservationKey) []RelatedObservation + States() []CheckState } -// NewReportContext returns a ReportContext backed by a primary payload and -// a pre-resolved map of related observations by key. The SDK's /report HTTP -// handler uses this to wrap ExternalReportRequest contents; hosts and tests -// can use it whenever they already have the related observations in memory. +// NewReportContext returns a ReportContext backed by a primary payload, a +// pre-resolved map of related observations by key, and the CheckStates +// produced by the checker's rules on this observation. The SDK's /report +// HTTP handler uses this to wrap ExternalReportRequest contents; hosts and +// tests can use it whenever they already have that material in memory. // -// Passing a nil or empty related map is fine; Related(key) will then return -// nil, just like StaticReportContext. -func NewReportContext(data json.RawMessage, related map[ObservationKey][]RelatedObservation) ReportContext { - return fixedReportContext{data: data, related: related} +// Passing a nil related map or a nil states slice is fine; Related(key) +// and States() will then return nil respectively. Use StaticReportContext +// as a shorthand when both are absent. +func NewReportContext(data json.RawMessage, related map[ObservationKey][]RelatedObservation, states []CheckState) ReportContext { + return fixedReportContext{data: data, related: related, states: states} } -// StaticReportContext is a shorthand for NewReportContext(data, nil): a -// ReportContext with a primary payload and no related observations. -// Intended for tests and ad-hoc callers that have no lineage to supply. +// StaticReportContext is a shorthand for NewReportContext(data, nil, nil): +// a ReportContext with a primary payload, no related observations, and no +// rule states. Intended for tests and ad-hoc callers that have no lineage +// or rule output to supply. func StaticReportContext(data json.RawMessage) ReportContext { return fixedReportContext{data: data} } @@ -331,6 +339,7 @@ func StaticReportContext(data json.RawMessage) ReportContext { type fixedReportContext struct { data json.RawMessage related map[ObservationKey][]RelatedObservation + states []CheckState } func (f fixedReportContext) Data() json.RawMessage { return f.data } @@ -340,6 +349,7 @@ func (f fixedReportContext) Related(key ObservationKey) []RelatedObservation { } return f.related[key] } +func (f fixedReportContext) States() []CheckState { return f.states } // CheckerHTMLReporter is an optional interface that observation providers can // implement to render their stored data as a full HTML document (for iframe embedding). @@ -486,13 +496,20 @@ type ExternalEvaluateResponse struct { // Related carries observations produced by other checkers on DiscoveryEntry // records originally published by the target of this report, that is, the // cross-checker lineage that ObservationGetter.GetRelated would expose in -// the in-process path. The host composes it before making the HTTP request; -// when absent, the remote checker receives a context that reports no -// related observations (equivalent to StaticReportContext). +// the in-process path. States carries the CheckStates the host produced by +// evaluating this checker's rules against the same observation, letting +// reporters render rule-driven sections (for example a "fix these first" +// list) without re-deriving severity or hints from Data. +// +// The host composes both fields before making the HTTP request. When both +// are absent, the remote checker receives a context equivalent to +// StaticReportContext (no related observations and no states); the +// reporter then falls back to a data-only rendering. type ExternalReportRequest struct { Key ObservationKey `json:"key"` Data json.RawMessage `json:"data"` Related map[ObservationKey][]RelatedObservation `json:"related,omitempty"` + States []CheckState `json:"states,omitempty"` } // HealthResponse is returned by GET /health on a remote checker endpoint. diff --git a/checker/types_test.go b/checker/types_test.go index 74b57d0..87022ee 100644 --- a/checker/types_test.go +++ b/checker/types_test.go @@ -15,10 +15,24 @@ package checker import ( + "context" "encoding/json" + "reflect" "testing" ) +// dummyRule is a minimal CheckRule used only by tests in this package. +type dummyRule struct { + name string + desc string +} + +func (r *dummyRule) Name() string { return r.name } +func (r *dummyRule) Description() string { return r.desc } +func (r *dummyRule) Evaluate(ctx context.Context, obs ObservationGetter, opts CheckerOptions) []CheckState { + return []CheckState{{Status: StatusOK, Message: r.name + " passed"}} +} + func TestStatus_MarshalJSON(t *testing.T) { tests := []struct { status Status @@ -143,6 +157,54 @@ func TestCheckerDefinition_BuildRulesInfo(t *testing.T) { } } +// Compile-time check that fixedReportContext implements ReportContext. +var _ ReportContext = fixedReportContext{} + +func TestStaticReportContext_NoExtras(t *testing.T) { + ctx := StaticReportContext(json.RawMessage(`{"k":"v"}`)) + if string(ctx.Data()) != `{"k":"v"}` { + t.Errorf("Data() = %s, want %s", ctx.Data(), `{"k":"v"}`) + } + if ctx.Related("any") != nil { + t.Error("Related(any) should be nil for StaticReportContext") + } + if ctx.States() != nil { + t.Error("States() should be nil for StaticReportContext") + } +} + +func TestNewReportContext_NilStates(t *testing.T) { + ctx := NewReportContext(json.RawMessage(`{}`), nil, nil) + if ctx.States() != nil { + t.Errorf("States() = %v, want nil", ctx.States()) + } +} + +func TestNewReportContext_PassesStates(t *testing.T) { + states := []CheckState{ + {Status: StatusWarn, Message: "heads up", RuleName: "r1"}, + {Status: StatusCrit, Message: "fix me", RuleName: "r2", Subject: "host.example"}, + } + ctx := NewReportContext(json.RawMessage(`{}`), nil, states) + got := ctx.States() + if !reflect.DeepEqual(got, states) { + t.Errorf("States() = %+v, want %+v", got, states) + } +} + +func TestNewReportContext_PassesRelated(t *testing.T) { + rel := map[ObservationKey][]RelatedObservation{ + "other.key": {{CheckerID: "other", Key: "other.key", Ref: "r1"}}, + } + ctx := NewReportContext(json.RawMessage(`{}`), rel, nil) + if got := ctx.Related("other.key"); len(got) != 1 || got[0].CheckerID != "other" { + t.Errorf("Related(other.key) = %+v, want one entry with CheckerID=other", got) + } + if ctx.Related("missing") != nil { + t.Error("Related(missing) should be nil") + } +} + func TestRegisterChecker_EmptyIDRejected(t *testing.T) { resetRegistries() RegisterChecker(&CheckerDefinition{ID: "", Name: "bad"})