checkers: load external checker plugins from .so files

Scan -plugins-directory paths at startup, open each .so via plugin.Open,
look up the NewCheckerPlugin symbol from checker-sdk-go, and register the
returned definition and observation provider in the global checker
registries. A pluginLoader indirection keeps the door open for future
plugin kinds.

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,140 @@
+// 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"
+
+	sdk "git.happydns.org/checker-sdk-go/checker"
+	"git.happydns.org/happyDomain/internal/checker"
+)
+
+// 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{
+	loadCheckerPlugin,
+}
+
+// loadCheckerPlugin handles the NewCheckerPlugin symbol exported by checkers
+// built against checker-sdk-go (see ../../checker-dummy/README.md).
+func loadCheckerPlugin(p *plugin.Plugin, fname string) (bool, error) {
+	sym, err := p.Lookup("NewCheckerPlugin")
+	if err != nil {
+		// Symbol not present in this .so — not an error.
+		return false, nil
+	}
+
+	factory, ok := sym.(func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error))
+	if !ok {
+		return true, fmt.Errorf("symbol NewCheckerPlugin has unexpected type %T", sym)
+	}
+
+	def, provider, err := factory()
+	if err != nil {
+		return true, err
+	}
+	if def == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil CheckerDefinition")
+	}
+	if provider == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil ObservationProvider")
+	}
+
+	checker.RegisterObservationProvider(provider)
+	checker.RegisterExternalizableChecker(def)
+	log.Printf("Plugin %s (%s) loaded", def.ID, fname)
+	return true, nil
+}
+
+// initPlugins scans each directory listed in cfg.PluginsDirectories and loads
+// every .so file found as a Go plugin. A directory that cannot be read is a
+// fatal configuration error; individual plugin failures are logged and
+// skipped so that one bad .so 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())
+
+			if err := loadPlugin(fname); 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, because the file might be a valid plugin for a future version of
+// happyDomain. The first loader error 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

@@ -62,6 +62,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(&stringSlice{&o.PluginsDirectories}, "plugins-directory", "Path to a directory containing checker plugins (.so files); may be repeated")
+
 	// Others flags are declared in some other files likes sources, storages, ... when they need specials configurations
 }
 

internal/config/custom.go

@@ -25,8 +25,27 @@ import (
 	"encoding/base64"
 	"net/mail"
 	"net/url"
+	"strings"
 )
 
+// stringSlice is a flag.Value that accumulates string values across repeated
+// invocations of the same flag (e.g. -plugins-directory a -plugins-directory b).
+type stringSlice struct {
+	Values *[]string
+}
+
+func (s *stringSlice) String() string {
+	if s.Values == nil {
+		return ""
+	}
+	return strings.Join(*s.Values, ",")
+}
+
+func (s *stringSlice) Set(value string) error {
+	*s.Values = append(*s.Values, value)
+	return nil
+}
+
 type JWTSecretKey struct {
 	Secret *[]byte
 }

model/config.go

@@ -103,6 +103,10 @@ 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 lists filesystem paths scanned at startup for
+	// checker plugins (.so files).
+	PluginsDirectories []string
 }
 
 // GetBaseURL returns the full url to the absolute ExternalURL, including BaseURL.