82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
# checker-sdk-go
|
|
|
|
Public Go SDK for writing [happyDomain](https://happydomain.org) 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
|
|
|
|
```bash
|
|
go get git.happydns.org/checker-sdk-go/checker
|
|
```
|
|
|
|
## Getting started
|
|
|
|
See [checker-dummy](https://git.happydns.org/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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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](LICENSE) and [NOTICE](NOTICE).
|