happyDomain/checker-dummy
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source
This commit is contained in:
nemunaire 2026-04-07 14:55:34 +07:00
commit 2ee9e93bf6
15 changed files with 1047 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
checker-dummy
*.so

14
Dockerfile Normal file
View file

@ -0,0 +1,14 @@
FROM golang:1.25-alpine AS builder
ARG CHECKER_VERSION=custom-build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags "-X main.Version=${CHECKER_VERSION}" -o /checker-dummy .
FROM scratch
COPY --from=builder /checker-dummy /checker-dummy
EXPOSE 8080
ENTRYPOINT ["/checker-dummy"]

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 The happyDomain Authors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

25
Makefile Normal file
View file

@ -0,0 +1,25 @@
CHECKER_NAME := checker-dummy
CHECKER_IMAGE := happydomain/$(CHECKER_NAME)
CHECKER_VERSION ?= custom-build
CHECKER_SOURCES := main.go $(wildcard checker/*.go)
GO_LDFLAGS := -X main.Version=$(CHECKER_VERSION)
.PHONY: all plugin docker clean
all: $(CHECKER_NAME)
$(CHECKER_NAME): $(CHECKER_SOURCES)
go build -ldflags "$(GO_LDFLAGS)" -o $@ .
plugin: $(CHECKER_NAME).so
$(CHECKER_NAME).so: $(CHECKER_SOURCES) $(wildcard plugin/*.go)
go build -buildmode=plugin -ldflags "$(GO_LDFLAGS)" -o $@ ./plugin/
docker:
docker build --build-arg CHECKER_VERSION=$(CHECKER_VERSION) -t $(CHECKER_IMAGE) .
clean:
rm -f $(CHECKER_NAME) $(CHECKER_NAME).so

26
NOTICE Normal file
View file

@ -0,0 +1,26 @@
checker-dummy
Copyright (c) 2026 The happyDomain Authors
This product is licensed under the MIT License (see LICENSE).
-------------------------------------------------------------------------------
Third-party notices
-------------------------------------------------------------------------------
This product includes software developed as part of the checker-sdk-go
project (https://git.happydns.org/happyDomain/checker-sdk-go), licensed
under the Apache License, Version 2.0:
checker-sdk-go
Copyright 2020-2026 The happyDomain Authors
This product includes software developed as part of the happyDomain
project (https://happydomain.org).
Portions of this code were originally written for the happyDomain
server (licensed under AGPL-3.0 and a commercial license) and are
made available there under the Apache License, Version 2.0 to enable
a permissively licensed ecosystem of checker plugins.
You may obtain a copy of the Apache License 2.0 at:
http://www.apache.org/licenses/LICENSE-2.0

544
README.md Normal file
View file

@ -0,0 +1,544 @@
# checker-dummy - How to Build a happyDomain Checker
This repository is a **fully working, educational example** of a happyDomain checker. It is intentionally simple: instead of performing real monitoring, it returns a random score and a user-configurable message. This lets you focus on learning the structure without dealing with external dependencies.
Use this as a template when you create your own checker.
---
## Table of Contents
1. [What is a Checker?](#what-is-a-checker)
2. [Architecture Overview](#architecture-overview)
3. [Repository Structure](#repository-structure)
4. [Step-by-Step Walkthrough](#step-by-step-walkthrough)
- [Step 1: Define Your Data Types](#step-1-define-your-data-types)
- [Step 2: Create the Provider](#step-2-create-the-provider)
- [Step 3: Implement Data Collection](#step-3-implement-data-collection)
- [Step 4: Describe Your Checker (Definition)](#step-4-describe-your-checker-definition)
- [Step 5: Write Evaluation Rules](#step-5-write-evaluation-rules)
- [Step 6: Wire It Up (main.go)](#step-6-wire-it-up-maingo)
- [Step 7: Create the Plugin Entrypoint](#step-7-create-the-plugin-entrypoint)
5. [Running the Checker](#running-the-checker)
6. [Testing with curl](#testing-with-curl)
7. [Deploying to happyDomain](#deploying-to-happydomain)
8. [License & happyDomain compatibility](#license--happydomain-compatibility)
9. [Going Further](#going-further)
---
## What is a Checker?
A **checker** is a small, self-contained program that monitors one aspect of a domain's DNS infrastructure. happyDomain runs checkers periodically and displays their results in its dashboard.
Every checker does three things:
1. **Collect:** Gather raw observation data (e.g., ping a server, query an API, measure DNS response time).
2. **Evaluate:** Compare the collected data against user-defined thresholds to produce a status: OK, Warning, or Critical.
3. **Report** *(optional)*: Extract time-series metrics or generate HTML reports for the dashboard.
## Architecture Overview
A checker can run in three modes:
### Standalone HTTP Server (External Checker)
The checker runs as its own process and exposes an HTTP API. happyDomain communicates with it over the network. This is the most flexible option: you can write your checker in any language, deploy it independently, and scale it separately.
```
┌─────────────┐ HTTP ┌─────────────────┐
│ happyDomain │ ──────────► │ checker-dummy │
│ server │ ◄────────── │ (this program) │
└─────────────┘ └─────────────────┘
```
### In-Process Plugin
The checker is compiled as a Go plugin (`.so` file) and loaded directly into the happyDomain process. This is simpler to deploy (single binary) but requires the checker to be written in Go.
```
┌──────────────────────────────────────┐
│ happyDomain server │
│ │
│ ┌──────────────────────────────┐ │
│ │ checker-dummy.so (plugin) │ │
│ │ checker-ping.so (plugin) │ │
│ │ checker-matrix.so (plugin) │ │
│ │ checker-....so (plugin) │ │
│ └──────────────────────────────┘ │
└──────────────────────────────────────┘
```
### Built-in Checker
The checker package can be imported directly into the happyDomain server and registered at init time: no plugin loading, no separate process. This avoids the operational burden of Go's plugin system (matching toolchain versions, CGO, `.so` distribution) entirely.
```go
// happydomain/checkers/ping.go
package checkers
import (
ping "git.happydns.org/checker-ping/checker"
"git.happydns.org/internal/checker"
)
func init() {
checker.RegisterObservationProvider(ping.Provider())
checker.RegisterExternalizableChecker(ping.Definition())
}
```
This mode is reserved for checkers maintained as part of the happyDomain project itself. Or if you compile yourself your own version of happyDomain.
**Both standalone, plugin and built-in modes use the same checker code; only the entry point differs.**
## Repository Structure
```
checker-dummy/
├── main.go # Entry point for standalone HTTP server mode
├── checker/
│ ├── types.go # Data structures (what the checker observes)
│ ├── provider.go # The provider: glues everything together
│ ├── collect.go # Collection logic (the actual monitoring)
│ ├── definition.go # Checker metadata (options, rules, intervals)
│ └── rule.go # Evaluation rules (OK / Warning / Critical)
├── plugin/
│ └── plugin.go # Entry point for plugin mode
├── go.mod # Go module definition
├── Makefile # Build targets
├── Dockerfile # Container image
└── .gitignore
```
Each file has a single, clear responsibility. This is the recommended layout for all happyDomain checkers.
---
## Step-by-Step Walkthrough
### Step 1: Define Your Data Types
**File: `checker/types.go`**
Start by defining the data structure that your checker will produce during collection. This struct is serialised to JSON by the SDK, stored by happyDomain, and later deserialised during evaluation.
```go
const ObservationKeyDummy = "dummy"
type DummyData struct {
Message string `json:"message"`
Score float64 `json:"score"`
CollectedAt time.Time `json:"collected_at"`
}
```
Key points:
- **`ObservationKeyDummy`** is a unique string that identifies observations produced by this checker. Every checker needs at least one key.
- **Design for evaluation**: include everything your rules will need to decide OK/Warning/Critical. The evaluation step only sees this struct; it cannot re-collect data.
### Step 2: Create the Provider
**File: `checker/provider.go`**
The **provider** is the central object of your checker. It must implement the `ObservationProvider` interface:
```go
type ObservationProvider interface {
Key() ObservationKey
Collect(ctx context.Context, opts CheckerOptions) (any, error)
}
```
You can also implement optional interfaces to unlock additional features:
| Interface | What it enables |
|-------------------------------|------------------------------------------|
| `CheckerDefinitionProvider` | `/definition` and `/evaluate` endpoints |
| `CheckerMetricsReporter` | `/report` endpoint (JSON metrics) |
| `CheckerHTMLReporter` | `/report` endpoint (HTML) |
In this example, we implement all three optional interfaces:
```go
type dummyProvider struct{}
func (p *dummyProvider) Key() ObservationKey { return ObservationKeyDummy }
func (p *dummyProvider) Definition() *CheckerDefinition { return Definition() }
func (p *dummyProvider) ExtractMetrics(raw json.RawMessage, collectedAt time.Time) ([]CheckMetric, error) { ... }
```
The `Key()` method must return the same string as your `ObservationKeyDummy` constant.
### Step 3: Implement Data Collection
**File: `checker/collect.go`**
This is where the real work happens. The `Collect` method is called every time happyDomain runs your check.
```go
func (p *dummyProvider) Collect(ctx context.Context, opts CheckerOptions) (any, error) {
// Read options using SDK helpers
message := "Hello from the dummy checker!"
if v, ok := sdk.GetOption[string](opts, "message"); ok && v != "" {
message = v
}
// Do your monitoring work here!
// In a real checker, you would: ping a server, query an API,
// measure DNS response time, check TLS certificates, etc.
score := rand.Float64() * 100
return &DummyData{
Message: message,
Score: score,
CollectedAt: time.Now(),
}, nil
}
```
Key points:
- **Always honour `ctx`**: happyDomain may cancel long-running checks.
- **Use SDK option helpers** (`sdk.GetOption`, `sdk.GetFloatOption`, `sdk.GetIntOption`, `sdk.GetBoolOption`) to read options. They handle type coercion between in-process (native Go types) and HTTP mode (JSON-decoded types).
- **Return your data struct**: the SDK serialises it to JSON automatically.
- **Return an error** only if collection failed entirely. Partial results are fine.
### Step 4: Describe Your Checker (Definition)
**File: `checker/definition.go`**
The `CheckerDefinition` tells happyDomain everything about your checker:
```go
func Definition() *CheckerDefinition {
return &CheckerDefinition{
ID: "dummy", // Unique, stable identifier (never change after release)
Name: "Dummy (example)", // Human-readable label for the UI
Version: Version, // Optional; injected at build time via -ldflags
Availability: CheckerAvailability{
ApplyToDomain: true, // Show in the "Domain checks" section
},
ObservationKeys: []ObservationKey{ObservationKeyDummy},
Options: CheckerOptionsDocumentation{
UserOpts: []CheckerOptionDocumentation{
{Id: "message", Type: "string", Label: "Custom message", Default: "Hello!"},
{Id: "warningThreshold", Type: "number", Label: "Warning threshold", Default: float64(50)},
...
},
},
Rules: []CheckRule{Rule()},
Interval: &CheckIntervalSpec{
Min: 1 * time.Minute, Max: 1 * time.Hour, Default: 5 * time.Minute,
},
HasMetrics: true,
}
}
```
**Version**: declare a package-level `var Version = "built-in"` in your checker package and reference it from the definition. The default is fine when the package is imported directly (built-in or plugin mode). For the standalone binary, declare a separate `var Version = "custom-build"` in `main.go` and propagate it in `init()`:
```go
// main.go
var Version = "custom-build"
func init() {
dummy.Version = Version
}
```
The CI can then override the standalone binary's version with a simple flag, without having to know the nested package path:
```bash
go build -ldflags "-X main.Version=$(git describe --tags)" .
```
**Availability**: choose where your checker appears:
| Field | When to use |
|------------------|-----------------------------------------------------|
| `ApplyToDomain` | The check applies to the entire domain |
| `ApplyToZone` | The check applies to a specific DNS zone |
| `ApplyToService` | The check applies to a specific service (e.g., A/AAAA records). Use `LimitToServices` to restrict which service types. |
**Options**: grouped by audience:
| Group | Who sets it | Example |
|---------------|----------------------|--------------------------------------|
| `AdminOpts` | happyDomain admin | API endpoint URL |
| `UserOpts` | End-user in the UI | Thresholds, count, custom messages |
| `DomainOpts` | Auto-filled per domain | `domain_name` (via `AutoFill`) |
| `ServiceOpts` | Auto-filled per service | The service payload (via `AutoFill`) |
| `RunOpts` | Set at collect-time | Runtime overrides |
**Option types** for the UI widget: `"string"`, `"number"`, `"uint"`, `"bool"`. You can also provide `Choices` for dropdown menus.
### Step 5: Write Evaluation Rules
**File: `checker/rule.go`**
A rule implements the `CheckRule` interface:
```go
type CheckRule interface {
Name() string
Description() string
Evaluate(ctx context.Context, obs ObservationGetter, opts CheckerOptions) CheckState
}
```
Optionally, your rule can also implement `ValidateOptions(opts) error` for early validation.
The `Evaluate` method receives an `ObservationGetter` to retrieve the collected data:
```go
func (r *dummyRule) Evaluate(ctx context.Context, obs ObservationGetter, opts CheckerOptions) CheckState {
var data DummyData
if err := obs.Get(ctx, ObservationKeyDummy, &data); err != nil {
return CheckState{Status: StatusError, Message: "..."}
}
warningThreshold := sdk.GetFloatOption(opts, "warningThreshold", 50)
criticalThreshold := sdk.GetFloatOption(opts, "criticalThreshold", 20)
switch {
case data.Score < criticalThreshold:
return CheckState{Status: StatusCrit, ...}
case data.Score < warningThreshold:
return CheckState{Status: StatusWarn, ...}
default:
return CheckState{Status: StatusOK, ...}
}
}
```
**Status values**: `StatusOK`, `StatusWarn`, `StatusCrit`, `StatusError`, `StatusUnknown`.
You can define **multiple rules** per checker. Each rule evaluates the same collected data from a different angle. Users can enable/disable rules individually in the UI.
### Step 6: Wire It Up (main.go)
**File: `main.go`**
The standalone entry point is minimal; the SDK does all the heavy lifting:
```go
func main() {
flag.Parse()
// Propagate the plugin's version to the checker package.
dummy.Version = Version
server := sdk.NewServer(dummy.Provider())
server.ListenAndServe(*listenAddr)
}
```
`sdk.NewServer` inspects your provider and automatically registers HTTP endpoints based on which interfaces it implements:
| Endpoint | Always | Requires |
|--------------------|--------|------------------------------|
| `GET /health` | Yes | - |
| `POST /collect` | Yes | - |
| `GET /definition` | - | `CheckerDefinitionProvider` |
| `POST /evaluate` | - | `CheckerDefinitionProvider` |
| `POST /report` | - | `CheckerMetricsReporter` or `CheckerHTMLReporter` |
### Step 7: Create the Plugin Entrypoint
**File: `plugin/plugin.go`**
For in-process plugin mode, the entrypoint must be a `package main` that exposes a `NewCheckerPlugin` symbol. happyDomain opens the `.so` file with `plugin.Open`, looks up that symbol, and calls it to obtain the checker definition and its observation provider, which the host then registers in its own global registries.
```go
package main
import (
sdk "git.happydns.org/checker-sdk-go/checker"
dummy "git.happydns.org/checker-dummy/checker"
)
var Version = "custom-build"
func NewCheckerPlugin() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
// Propagate the plugin's version to the checker package.
dummy.Version = Version
return dummy.Definition(), dummy.Provider(), nil
}
```
Build the plugin with:
```bash
go build -buildmode=plugin -o checker-dummy.so ./plugin
```
Then drop the resulting `checker-dummy.so` into one of happyDomain's configured plugin directories. It will be picked up at startup.
---
## Running the Checker
### Build and run locally
```bash
make build
./checker-dummy -listen :8080
```
### Docker
```bash
make docker
docker run -p 8080:8080 happydomain/checker-dummy
```
---
## Testing with curl
### Health check
```bash
curl http://localhost:8080/health
# {"status":"ok"}
```
### Get the checker definition
```bash
curl http://localhost:8080/definition
```
### Collect an observation
```bash
curl -X POST http://localhost:8080/collect \
-H "Content-Type: application/json" \
-d '{
"key": "dummy",
"options": {
"message": "Testing my checker!"
}
}'
```
Response:
```json
{
"data": {
"message": "Testing my checker!",
"score": 73.2,
"collected_at": "2026-01-15T10:30:00Z"
}
}
```
### Evaluate observations
```bash
curl -X POST http://localhost:8080/evaluate \
-H "Content-Type: application/json" \
-d '{
"observations": {
"dummy": "{\"message\":\"test\",\"score\":42.5,\"collected_at\":\"2026-01-15T10:30:00Z\"}"
},
"options": {
"warningThreshold": 50,
"criticalThreshold": 20
}
}'
```
Response (score 42.5 is below the warning threshold of 50):
```json
{
"states": [
{
"status": 3,
"message": "Score: 42.5 - test",
"code": "dummy_score_check"
}
]
}
```
Status codes: `1` = OK, `3` = Warning, `4` = Critical.
### Extract metrics
```bash
curl -X POST http://localhost:8080/report \
-H "Content-Type: application/json" \
-d '{
"data": "{\"message\":\"test\",\"score\":73.2,\"collected_at\":\"2026-01-15T10:30:00Z\"}"
}'
```
---
## Deploying to happyDomain
### As an external checker (recommended)
1. Deploy your checker as a standalone service (Docker, systemd, etc.).
2. In happyDomain, set the checker's `endpoint` admin option to its URL (e.g., `http://checker-dummy:8080`).
3. happyDomain will call `/collect`, `/evaluate`, and `/report` automatically.
### As an in-process plugin
1. Build the plugin:
```bash
go build -buildmode=plugin -o checker-dummy.so ./plugin
```
2. Copy `checker-dummy.so` into one of the directories listed in happyDomain's `PluginsDirectories` configuration.
3. Restart happyDomain. At startup it scans those directories, opens each `.so`, looks up the `NewCheckerPlugin` symbol, and registers the returned definition and provider.
---
## License & happyDomain compatibility
This template is released under the **MIT License**, so you're free to use it as a starting point for any checker, including proprietary ones.
The types and helpers your checker depends on live in [`checker-sdk-go`](https://git.happydns.org/checker-sdk-go), a separate module released under the **Apache License 2.0**. happyDomain itself depends on the same SDK, so plugins and the host share a common, permissively licensed contract instead of linking against AGPL code.
**What this means for the deployment mode you choose:**
- **Standalone HTTP checker:** your checker is a separate process communicating with happyDomain over the network. It is *not* a derivative work of happyDomain and you can license it however you want (proprietary, MIT, GPL, anything).
- **In-process plugin (`.so`):** your checker is loaded into the happyDomain process via `plugin.Open`, but it only links against the Apache-licensed SDK — not against any AGPL code. You are free to license your plugin however you want.
- **Built-in checker** (imported directly into the happyDomain source tree): same as above on the linking side. Built-in checkers maintained inside the happyDomain repository are conventionally distributed under AGPL-3.0 to stay consistent with the rest of the project, but this is a project policy, not a legal requirement coming from the SDK.
If your checker imports anything *else* from the happyDomain repository (for example service abstractions like `happydns.ServiceMessage`), then that code *is* AGPL-licensed and the AGPL constraint comes back. The SDK alone is safe; the rest of happyDomain is not.
---
## Going Further
Now that you understand the structure, here are ideas for your own checker:
- **SMTP checker:** connect to a mail server and verify it responds correctly to EHLO.
- **DNS checker:** query specific DNS record types and verify the response matches expectations.
- **HTTP checker:** send an HTTP request to a domain's web server and check the status code, response time, ...
- **Business logic:** probe your own application from the outside and verify it behaves as expected, e.g. log into your SaaS with a synthetic account and check that the dashboard loads, place a test order and confirm it reaches the order pipeline, hit an internal health endpoint that aggregates queue depth / worker lag / replication status, or check that a license server still hands out valid tokens. This turns happyDomain into a lightweight synthetic-monitoring dashboard for your own services.
For a real-world example, look at [checker-ping](https://git.happydns.org/checker-ping), which implements ICMP ping monitoring with multiple targets, packet loss detection, and RTT metrics.
### Tips
- Keep `Collect` focused on data gathering. Put all threshold logic in `Evaluate`.
- Design your data struct to hold everything rules need; evaluation cannot re-collect.
- Use `sdk.GetFloatOption` / `sdk.GetIntOption` / `sdk.GetBoolOption` instead of raw type assertions. They handle the JSON/native type mismatch transparently.
- Always honour the `context.Context`: set timeouts and check for cancellation.
- Return partial results from `Collect` when possible (only return an error if the entire collection failed).

46
checker/collect.go Normal file
View file

@ -0,0 +1,46 @@
package checker
import (
"context"
"math/rand/v2"
"time"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Collect gathers observation data. This is called by happyDomain (or the
// /collect HTTP endpoint) every time a check runs.
//
// In a real checker, this is where you would perform the actual monitoring
// work: sending network requests, querying APIs, measuring latency, etc.
//
// This dummy implementation simply reads options and generates a random score
// so you can focus on the structure rather than external dependencies.
//
// Parameters:
// - ctx: a context for cancellation/timeout - always honour it.
// - opts: the merged checker options (admin + user + domain + service + run).
//
// Return:
// - any: the observation data (will be JSON-serialised by the SDK).
// - error: non-nil if collection failed entirely.
func (p *dummyProvider) Collect(ctx context.Context, opts sdk.CheckerOptions) (any, error) {
// Read user-configurable options using the SDK helpers.
// These helpers handle type coercion gracefully - the value may come as
// a native Go type (in-process plugin) or as a JSON-decoded float64/string
// (external HTTP mode). The helpers normalise both cases.
message := "Hello from the dummy checker!"
if v, ok := sdk.GetOption[string](opts, "message"); ok && v != "" {
message = v
}
// Generate a random score between 0 and 100 to simulate a measurement.
// In your real checker, replace this with actual monitoring logic.
score := rand.Float64() * 100
return &DummyData{
Message: message,
Score: score,
CollectedAt: time.Now(),
}, nil
}

116
checker/definition.go Normal file
View file

@ -0,0 +1,116 @@
package checker
import (
"time"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Version is the checker version reported in CheckerDefinition.Version.
//
// It defaults to "built-in", which is appropriate when the checker package is
// imported directly (built-in or plugin mode). Standalone binaries (like
// main.go) should override this from their own Version variable at the start
// of main(), which makes it easy for CI to inject a version with a single
// -ldflags "-X main.Version=..." flag instead of targeting the nested
// package path.
var Version = "built-in"
// Definition returns the CheckerDefinition for the dummy checker.
//
// A CheckerDefinition tells happyDomain everything it needs to know about
// your checker: its identity, where it can be applied, what options it
// accepts, what rules it provides, and how often it should run.
func Definition() *sdk.CheckerDefinition {
return &sdk.CheckerDefinition{
// ID is a unique, stable identifier for this checker. It is stored in
// the database, so never change it after release.
ID: "dummy",
// Name is the human-readable label shown in the happyDomain UI.
Name: "Dummy (example)",
// Version is an optional version string for this checker. It is
// surfaced in the UI/API and is useful to track which iteration of
// your checker produced a given observation. The value is injected
// at build time via -ldflags "-X .../checker.Version=...".
Version: Version,
// Availability controls where this checker appears in the UI.
// A checker can apply at the domain level, zone level, or service
// level. You can also restrict it to specific service types.
//
// Here we apply it at the domain level, which means users will see
// this checker in the "Domain checks" section and it does not require
// a specific service to be present.
Availability: sdk.CheckerAvailability{
ApplyToDomain: true,
},
// ObservationKeys lists the keys this checker produces. This ties
// the definition to the provider(s) that generate the data.
ObservationKeys: []sdk.ObservationKey{ObservationKeyDummy},
// Options documents what configuration the checker accepts. Options
// are grouped by audience (admin, user, domain, service, run):
//
// - AdminOpts: set once by the happyDomain administrator
// - UserOpts: editable by end-users in the checker settings UI
// - DomainOpts: auto-filled per domain (domain_name, etc.)
// - ServiceOpts: auto-filled per service (the service payload)
// - RunOpts: set at collect-time only (e.g., overrides)
//
// Each option has an Id (used as the key in CheckerOptions), a Type
// for the UI widget, a Label, and optionally a Default value.
Options: sdk.CheckerOptionsDocumentation{
UserOpts: []sdk.CheckerOptionDocumentation{
{
Id: "message",
Type: "string",
Label: "Custom message",
Description: "A message that will be included in the observation data.",
Default: "Hello from the dummy checker!",
},
{
Id: "warningThreshold",
Type: "number",
Label: "Warning threshold (score)",
Description: "If the score drops below this value, the check status becomes Warning.",
Default: float64(50),
},
{
Id: "criticalThreshold",
Type: "number",
Label: "Critical threshold (score)",
Description: "If the score drops below this value, the check status becomes Critical.",
Default: float64(20),
},
},
DomainOpts: []sdk.CheckerOptionDocumentation{
{
Id: "domain_name",
Label: "Domain name",
AutoFill: sdk.AutoFillDomainName,
},
},
},
// Rules lists the evaluation rules provided by this checker. Each
// rule will appear in the UI, and users can enable/disable them
// individually.
Rules: []sdk.CheckRule{
Rule(),
},
// Interval specifies how often the check should run.
Interval: &sdk.CheckIntervalSpec{
Min: 1 * time.Minute,
Max: 1 * time.Hour,
Default: 5 * time.Minute,
},
// HasMetrics indicates that this checker can produce time-series
// metrics (because our provider implements CheckerMetricsReporter).
HasMetrics: true,
}
}

61
checker/provider.go Normal file
View file

@ -0,0 +1,61 @@
package checker
import (
"encoding/json"
"time"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Provider returns a new dummy observation provider.
//
// The provider is the central object of a checker. It implements the
// ObservationProvider interface (required) and can optionally implement
// additional interfaces to unlock more features:
//
// - CheckerDefinitionProvider → exposes /definition and /evaluate endpoints
// - CheckerMetricsReporter → exposes /report (JSON metrics) endpoint
// - CheckerHTMLReporter → exposes /report (HTML) endpoint
//
// In this example, the provider implements all three optional interfaces
// so you can see how each one works.
func Provider() sdk.ObservationProvider {
return &dummyProvider{}
}
// dummyProvider is the concrete type that satisfies the ObservationProvider
// interface and the optional reporter interfaces.
type dummyProvider struct{}
// Key returns the observation key for this provider. This must match the key
// used in your CheckerDefinition's ObservationKeys list so happyDomain knows
// which provider produces which data.
func (p *dummyProvider) Key() sdk.ObservationKey {
return ObservationKeyDummy
}
// Definition implements sdk.CheckerDefinitionProvider.
// Returning a definition enables the /definition and /evaluate HTTP endpoints
// in the SDK server, and lets happyDomain discover this checker's metadata.
func (p *dummyProvider) Definition() *sdk.CheckerDefinition {
return Definition()
}
// ExtractMetrics implements sdk.CheckerMetricsReporter.
// This is called when happyDomain (or the /report endpoint) needs to turn
// raw observation data into time-series metrics for graphing.
func (p *dummyProvider) ExtractMetrics(raw json.RawMessage, collectedAt time.Time) ([]sdk.CheckMetric, error) {
var data DummyData
if err := json.Unmarshal(raw, &data); err != nil {
return nil, err
}
return []sdk.CheckMetric{
{
Name: "dummy_score",
Value: data.Score,
Unit: "points",
Timestamp: collectedAt,
},
}, nil
}

96
checker/rule.go Normal file
View file

@ -0,0 +1,96 @@
package checker
import (
"context"
"fmt"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Rule returns a new dummy check rule.
//
// A rule evaluates collected observation data and returns a status (OK,
// Warning, Critical, Error). Each checker can define multiple rules that
// inspect the same data from different angles.
func Rule() sdk.CheckRule {
return &dummyRule{}
}
// dummyRule implements the sdk.CheckRule interface.
type dummyRule struct{}
// Name returns a unique, stable identifier for this rule. It is used as the
// "code" field in check results and stored in the database.
func (r *dummyRule) Name() string { return "dummy_score_check" }
// Description returns a human-readable summary of what this rule checks.
func (r *dummyRule) Description() string {
return "Checks whether the dummy score is above the configured thresholds"
}
// ValidateOptions is called before evaluation to verify that the options are
// well-formed. Return an error to reject invalid configuration early, before
// any data collection happens.
func (r *dummyRule) ValidateOptions(opts sdk.CheckerOptions) error {
warning := sdk.GetFloatOption(opts, "warningThreshold", 50)
critical := sdk.GetFloatOption(opts, "criticalThreshold", 20)
if warning < 0 || warning > 100 {
return fmt.Errorf("warningThreshold must be between 0 and 100")
}
if critical < 0 || critical > 100 {
return fmt.Errorf("criticalThreshold must be between 0 and 100")
}
if critical >= warning {
return fmt.Errorf("criticalThreshold (%v) must be less than warningThreshold (%v)", critical, warning)
}
return nil
}
// Evaluate inspects the collected observation data and returns a CheckState.
//
// Parameters:
// - ctx: context for cancellation.
// - obs: an ObservationGetter to retrieve collected data by key.
// - opts: the merged checker options.
//
// The ObservationGetter.Get method deserialises the stored JSON into your data
// struct. Always check the error: the observation may not be available if
// collection failed.
func (r *dummyRule) Evaluate(ctx context.Context, obs sdk.ObservationGetter, opts sdk.CheckerOptions) sdk.CheckState {
// Retrieve the observation data by key.
var data DummyData
if err := obs.Get(ctx, ObservationKeyDummy, &data); err != nil {
return sdk.CheckState{
Status: sdk.StatusError,
Message: fmt.Sprintf("Failed to get dummy data: %v", err),
Code: "dummy_error",
}
}
// Read thresholds from options.
warningThreshold := sdk.GetFloatOption(opts, "warningThreshold", 50)
criticalThreshold := sdk.GetFloatOption(opts, "criticalThreshold", 20)
// Determine the status based on the score and thresholds.
var status sdk.Status
switch {
case data.Score < criticalThreshold:
status = sdk.StatusCrit
case data.Score < warningThreshold:
status = sdk.StatusWarn
default:
status = sdk.StatusOK
}
return sdk.CheckState{
Status: status,
Message: fmt.Sprintf("Score: %.1f - %s", data.Score, data.Message),
Code: "dummy_score_check",
Meta: map[string]any{
"score": data.Score,
"message": data.Message,
},
}
}

33
checker/types.go Normal file
View file

@ -0,0 +1,33 @@
// Package checker implements a dummy checker for happyDomain.
//
// This is an educational example that demonstrates all the building blocks
// needed to create a happyDomain checker. It performs no real monitoring;
// instead, it returns a configurable message and a random score, so you can
// focus on the structure without worrying about external dependencies.
package checker
import "time"
// ObservationKeyDummy is the unique key that identifies observations
// produced by this checker. Every checker must define at least one key so
// happyDomain can store and retrieve its data.
const ObservationKeyDummy = "dummy"
// DummyData is the data structure returned by Collect.
//
// When happyDomain collects an observation, it serialises this struct to JSON
// and stores it. Later, during evaluation, the same JSON is deserialised back
// into this struct. Design this type to hold everything your rules will need
// to decide OK / Warning / Critical.
type DummyData struct {
// Message is an arbitrary string returned as part of the observation.
Message string `json:"message"`
// Score is a number between 0 and 100. The evaluation rules compare it
// against user-defined thresholds to determine the check status.
Score float64 `json:"score"`
// CollectedAt records when the observation was taken. It is used by the
// metrics reporter to timestamp the extracted metrics.
CollectedAt time.Time `json:"collected_at"`
}

5
go.mod Normal file
View file

@ -0,0 +1,5 @@
module git.happydns.org/checker-dummy
go 1.25.0
require git.happydns.org/checker-sdk-go v0.0.1

2
go.sum Normal file
View file

@ -0,0 +1,2 @@
git.happydns.org/checker-sdk-go v0.0.1 h1:4RxCJr73HWKxjOyU/6NJMO8lXJmH0gMLA68EzTqLbQI=
git.happydns.org/checker-sdk-go v0.0.1/go.mod h1:aNAcfYFfbhvH9kJhE0Njp5GX0dQbxdRB0rJ0KvSC5nI=

30
main.go Normal file
View file

@ -0,0 +1,30 @@
package main
import (
"flag"
"log"
dummy "git.happydns.org/checker-dummy/checker"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Version is the standalone binary's version. It defaults to "custom-build"
// and is meant to be overridden by the CI at link time:
//
// go build -ldflags "-X main.Version=1.2.3" .
var Version = "custom-build"
var listenAddr = flag.String("listen", ":8080", "HTTP listen address")
func main() {
flag.Parse()
// Propagate the binary version to the checker package so it shows up in
// CheckerDefinition.Version.
dummy.Version = Version
server := sdk.NewServer(dummy.Provider())
if err := server.ListenAndServe(*listenAddr); err != nil {
log.Fatalf("server error: %v", err)
}
}

26
plugin/plugin.go Normal file
View file

@ -0,0 +1,26 @@
// Command plugin is the happyDomain plugin entrypoint for the dummy checker.
//
// It is built as a Go plugin (`go build -buildmode=plugin`) and loaded at
// runtime by happyDomain.
package main
import (
dummy "git.happydns.org/checker-dummy/checker"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Version is the plugin's version. It defaults to "custom-build" and is
// meant to be overridden by the CI at link time:
//
// go build -buildmode=plugin -ldflags "-X main.Version=1.2.3" -o checker-dummy.so ./plugin
var Version = "custom-build"
// NewCheckerPlugin is the symbol resolved by happyDomain when loading the
// .so file. It returns the checker definition and the observation provider
// that the host will register in its global registries.
func NewCheckerPlugin() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
// Propagate the plugin's version to the checker package so it shows up
// in CheckerDefinition.Version.
dummy.Version = Version
return dummy.Definition(), dummy.Provider(), nil
}