commit 2ee9e93bf68f94719b0bc7f094e79bcbfdde2dfe Author: Pierre-Olivier Mercier Date: Tue Apr 7 14:55:34 2026 +0700 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..78396f4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +checker-dummy +*.so diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..84da623 --- /dev/null +++ b/Dockerfile @@ -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"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..07d44d8 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6ccbd22 --- /dev/null +++ b/Makefile @@ -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 diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..ae61715 --- /dev/null +++ b/NOTICE @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ef4d2e --- /dev/null +++ b/README.md @@ -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). diff --git a/checker/collect.go b/checker/collect.go new file mode 100644 index 0000000..15b75d9 --- /dev/null +++ b/checker/collect.go @@ -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 +} diff --git a/checker/definition.go b/checker/definition.go new file mode 100644 index 0000000..3c4d99e --- /dev/null +++ b/checker/definition.go @@ -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, + } +} diff --git a/checker/provider.go b/checker/provider.go new file mode 100644 index 0000000..5543940 --- /dev/null +++ b/checker/provider.go @@ -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 +} diff --git a/checker/rule.go b/checker/rule.go new file mode 100644 index 0000000..2427468 --- /dev/null +++ b/checker/rule.go @@ -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, + }, + } +} diff --git a/checker/types.go b/checker/types.go new file mode 100644 index 0000000..5bf4a32 --- /dev/null +++ b/checker/types.go @@ -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"` +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..c4aaafb --- /dev/null +++ b/go.mod @@ -0,0 +1,5 @@ +module git.happydns.org/checker-dummy + +go 1.25.0 + +require git.happydns.org/checker-sdk-go v0.0.1 diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..5282be1 --- /dev/null +++ b/go.sum @@ -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= diff --git a/main.go b/main.go new file mode 100644 index 0000000..2ab77ee --- /dev/null +++ b/main.go @@ -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) + } +} diff --git a/plugin/plugin.go b/plugin/plugin.go new file mode 100644 index 0000000..cc6499e --- /dev/null +++ b/plugin/plugin.go @@ -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 +}