Load checks plugins

checks/interface.go

@@ -0,0 +1,72 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// Package checks provides the registry for domain health checkers.
+// It allows individual checker implementations to self-register at startup
+// via init() functions and exposes functions to retrieve registered checkers.
+package checks // import "git.happydns.org/happyDomain/checks"
+
+import (
+	"fmt"
+	"log"
+
+	"git.happydns.org/happyDomain/model"
+)
+
+// checkersList is the ordered list of all registered checks.
+var checkersList map[string]happydns.Checker = map[string]happydns.Checker{}
+
+// RegisterChecker declares the existence of the given check. It is intended to
+// be called from init() functions in individual check files so that each check
+// self-registers at program startup.
+//
+// If two checks try to register the same environment name the program will
+// terminate: name collisions are a configuration error, not a runtime one.
+func RegisterChecker(name string, checker happydns.Checker) {
+	log.Println("Registering new checker:")
+	checkersList[name] = checker
+}
+
+// GetCheckers returns the ordered list of all registered checks.
+func GetCheckers() *map[string]happydns.Checker {
+	return &checkersList
+}
+
+// FindChecker returns the check registered under the given environment name,
+// or an error if no check with that name exists.
+func FindChecker(name string) (happydns.Checker, error) {
+	c, ok := checkersList[name]
+	if !ok {
+		return nil, fmt.Errorf("unable to find check %q", name)
+	}
+	return c, nil
+}
+
+// GetCheckInterval returns the checker's preferred scheduling bounds,
+// or nil if the checker does not implement CheckerIntervalProvider.
+func GetCheckInterval(checker happydns.Checker) *happydns.CheckIntervalSpec {
+	ip, ok := checker.(happydns.CheckerIntervalProvider)
+	if !ok {
+		return nil
+	}
+	spec := ip.CheckInterval()
+	return &spec
+}

internal/app/app.go

@@ -93,6 +93,9 @@ func NewApp(cfg *happydns.Options) *App {
 	app.initStorageEngine()
 	app.initNewsletter()
 	app.initInsights()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()
@@ -108,6 +111,9 @@ func NewAppWithStorage(cfg *happydns.Options, store storage.Storage) *App {
 
 	app.initMailer()
 	app.initNewsletter()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()

internal/app/plugins.go

@@ -0,0 +1,134 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package app
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"plugin"
+
+	"git.happydns.org/happyDomain/checks"
+	"git.happydns.org/happyDomain/model"
+)
+
+// pluginLoader attempts to find and register one specific kind of plugin
+// symbol from an already-opened .so file.
+//
+// It returns (true, nil) when the symbol was found and registration
+// succeeded, (true, err) when the symbol was found but something went wrong,
+// and (false, nil) when the symbol simply isn't present in that file (which
+// is not considered an error — a single .so may implement only a subset of
+// the known plugin types).
+type pluginLoader func(p *plugin.Plugin, fname string) (found bool, err error)
+
+// pluginLoaders is the authoritative list of plugin types that happyDomain
+// knows about. To support a new plugin type, add a single entry here.
+var pluginLoaders = []pluginLoader{
+	loadCheckPlugin,
+}
+
+// loadCheckPlugin handles the NewTestPlugin symbol.
+func loadCheckPlugin(p *plugin.Plugin, fname string) (bool, error) {
+	sym, err := p.Lookup("NewCheckPlugin")
+	if err != nil {
+		// Symbol not present in this .so — not an error.
+		return false, nil
+	}
+
+	factory, ok := sym.(func() (string, happydns.Checker, error))
+	if !ok {
+		return true, fmt.Errorf("symbol NewCheckPlugin has unexpected type %T", sym)
+	}
+
+	pluginname, myplugin, err := factory()
+	if err != nil {
+		return true, err
+	}
+
+	checks.RegisterChecker(pluginname, myplugin)
+	log.Printf("Plugin %s loaded", pluginname)
+	return true, nil
+}
+
+// initPlugins scans each directory listed in cfg.PluginsDirectories, loads
+// every .so file found as a Go plugin, and registers it in the application's
+// PluginManager. All load errors are collected and returned as a joined error
+// so that a single bad plugin does not prevent the others from loading.
+func (a *App) initPlugins() error {
+	for _, directory := range a.cfg.PluginsDirectories {
+		files, err := os.ReadDir(directory)
+		if err != nil {
+			return fmt.Errorf("unable to read plugins directory %q: %s", directory, err)
+		}
+
+		for _, file := range files {
+			if file.IsDir() {
+				continue
+			}
+
+			// Only attempt to load shared-object files.
+			if filepath.Ext(file.Name()) != ".so" {
+				continue
+			}
+
+			fname := filepath.Join(directory, file.Name())
+
+			err = loadPlugin(fname)
+			if err != nil {
+				log.Printf("Unable to load plugin %q: %s", fname, err)
+			}
+		}
+	}
+
+	return nil
+}
+
+// loadPlugin opens the .so file at fname and runs every registered
+// pluginLoader against it. A loader that does not find its symbol is silently
+// skipped. If no loader recognises any symbol in the file a warning is logged,
+// but no error is returned because the file might be a valid plugin for a
+// future version of happyDomain. The first loader error that is encountered
+// is returned immediately.
+func loadPlugin(fname string) error {
+	p, err := plugin.Open(fname)
+	if err != nil {
+		return err
+	}
+
+	anyFound := false
+	for _, loader := range pluginLoaders {
+		found, err := loader(p, fname)
+		if err != nil {
+			return err
+		}
+		if found {
+			anyFound = true
+		}
+	}
+
+	if !anyFound {
+		log.Printf("Warning: plugin %q exports no recognised symbols", fname)
+	}
+	return nil
+}

internal/config/cli.go

@@ -60,6 +60,8 @@ func declareFlags(o *happydns.Options) {
 	flag.StringVar(&o.CaptchaProvider, "captcha-provider", o.CaptchaProvider, "Captcha provider to use for bot protection (altcha, hcaptcha, recaptchav2, turnstile, or empty to disable)")
 	flag.IntVar(&o.CaptchaLoginThreshold, "captcha-login-threshold", 3, "Number of failed login attempts before captcha is required (0 = always require when provider configured)")
 
+	flag.Var(&ArrayArgs{&o.PluginsDirectories}, "plugins-directory", "Path to a directory containing plugins (can be repeated multiple times)")
+
 	// Others flags are declared in some other files likes sources, storages, ... when they need specials configurations
 }
 

model/check_result.go

@@ -0,0 +1,28 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package happydns
+
+type CheckResult struct {
+	Status     CheckResultStatus `json:"status"`
+	StatusLine string            `json:"statusLine,omitempty"`
+	Report     any               `json:"report"`
+}

model/checker.go

@@ -0,0 +1,66 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package happydns
+
+import (
+	"context"
+	"time"
+)
+
+const (
+	CheckResultStatusUnknown CheckResultStatus = iota
+	CheckResultStatusCritical
+	CheckResultStatusWarn
+	CheckResultStatusInfo
+	CheckResultStatusOK
+)
+
+type CheckResultStatus int
+
+type Checker interface {
+	ID() string
+	Name() string
+	Availability() CheckerAvailability
+	RunCheck(ctx context.Context, options map[string]any, meta map[string]string) (*CheckResult, error)
+}
+
+// CheckIntervalSpec describes the scheduling bounds for a checker.
+type CheckIntervalSpec struct {
+	Min     time.Duration `json:"min" swaggertype:"integer"`
+	Max     time.Duration `json:"max" swaggertype:"integer"`
+	Default time.Duration `json:"default" swaggertype:"integer"`
+}
+
+// CheckerIntervalProvider is an optional interface checkers can implement
+// to declare their preferred scheduling bounds. The scheduler enforces
+// Min/Max; Default is used when creating a new schedule with no explicit interval.
+type CheckerIntervalProvider interface {
+	CheckInterval() CheckIntervalSpec
+}
+
+type CheckerAvailability struct {
+	ApplyToDomain    bool     `json:"applyToDomain,omitempty"`
+	ApplyToZone      bool     `json:"applyToZone,omitempty"`
+	ApplyToService   bool     `json:"applyToService,omitempty"`
+	LimitToProviders []string `json:"limitToProviders,omitempty"`
+	LimitToServices  []string `json:"limitToServices,omitempty"`
+}

model/config.go

@@ -99,6 +99,8 @@ type Options struct {
 	// CaptchaLoginThreshold is the number of consecutive login failures before captcha is required.
 	// 0 means always require captcha at login (when provider is configured).
 	CaptchaLoginThreshold int
+
+	PluginsDirectories []string
 }
 
 // GetBaseURL returns the full url to the absolute ExternalURL, including BaseURL.