happyDomain/checker-sdk-go
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
21 commits 2 branches 14 tags 128 KiB
  • Go 100%
Find a file
Exact
Pierre-Olivier Mercier 89cc3f112b server: split HTTP scaffolding into its own subpackage 
Move server.go and interactive.go (and their tests) from the root
checker/ package into checker/server/. Plugin and builtin consumers of
the SDK now import only checker/ and no longer drag net/http,
html/template, or the form-rendering code into their artifacts: on
checker-dane.so this drops the binary by ~1.2 MB and removes 170
html/template symbols along with the net/http contribution that came
from the SDK itself.

Breaking for standalone consumers (main.go):

  NewServer(p)                  -> server.New(p)
  CheckerInteractive            -> server.Interactive
  InteractiveRelatedProviders   -> server.Siblings

Providers that only satisfy the interactive interfaces structurally
(method set match, no explicit type reference) need no source change;
only main.go has to switch its import path and the constructor name.
2026-04-24 12:31:53 +07:00
checker server: split HTTP scaffolding into its own subpackage 2026-04-24 12:31:53 +07:00
go.mod Initial commit 2026-04-08 00:53:15 +07:00
LICENSE Initial commit 2026-04-08 00:53:15 +07:00
NOTICE Initial commit 2026-04-08 00:53:15 +07:00
README.md Fix comments 2026-04-24 11:22:22 +07:00

README.md

checker-sdk-go

Public Go SDK for writing happyDomain checker plugins.

This module provides the stable types, helpers, and HTTP server scaffolding that all checker plugins need, independent of the happyDomain server itself.

Why a separate module?

The happyDomain server is licensed under AGPL-3.0 (with a commercial option). If checkers had to import the server's internal packages, every checker, even trivial ones, would inherit those licensing constraints.

This SDK is released under the Apache License 2.0, so:

  • You can write a checker plugin under any license you want (MIT, Apache, proprietary, AGPL, whatever fits your needs).
  • A plugin built against this SDK is not a derivative work of happyDomain.
  • happyDomain itself depends on this SDK (as an Apache-licensed dependency, which is compatible with AGPL).

Installation

go get git.happydns.org/checker-sdk-go/checker

Getting started

See checker-dummy for a fully working, documented template.

Extending the server

checker.Server exposes the standard SDK routes (/health, /collect, and, depending on the provider's optional interfaces, /definition, /evaluate, /report). Plugins that need to serve auxiliary endpoints (debug pages, webhooks, custom UI assets, …) can register them on the same mux:

srv := checker.NewServer(provider)

srv.HandleFunc("GET /debug/state", func(w http.ResponseWriter, r *http.Request) {
    // …
})

// Opt a custom route into the in-flight / load-average signal
// reported on /health:
srv.Handle("POST /webhook", srv.TrackWork(myWebhookHandler))

log.Fatal(srv.ListenAndServe(":8080"))

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.

Standalone human UI (/check)

Providers that implement CheckerInteractive get a built-in human-facing web form on /check, usable outside of happyDomain:

type CheckerInteractive interface {
    RenderForm() []CheckerOptionField
    ParseForm(r *http.Request) (CheckerOptions, error)
}
  • GET /check renders a form derived from RenderForm().
  • POST /check calls ParseForm to obtain CheckerOptions, runs the standard Collect → Evaluate → GetHTMLReport / ExtractMetrics 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 own DNS queries from the human-supplied inputs.

License

Apache License 2.0. See LICENSE and NOTICE.