Pierre-Olivier Mercier
0c6a886e82
Lets plugins register auxiliary endpoints (debug pages, webhooks, UI assets) on the SDK mux, with TrackWork as an opt-in for the /health load signal.
61 lines
1.9 KiB
Markdown
61 lines
1.9 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`.
|
|
|
|
## License
|
|
|
|
Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|