watcher

Documentation

Overview

Package watcher provides fsnotify-based directory watching with debounced matcher recompilation. It watches whitelist and blacklist directories and rebuilds compiled matchers atomically when files change.

Index

• func Start(cfg *Config) (stop func() error, err error)
• type Config
• type Logger
• type Snapshot

Functions

func Start

func Start(cfg *Config) (stop func() error, err error)

Start begins watching the configured directories and returns a stop function.

The cfg parameter supplies watched directories, compile limits, and optional callbacks for update and error reporting. Start performs the first load and compilation before returning, but it keeps the watcher alive when directories are unreadable, empty, or contain only unsupported rules. Those outcomes are logged in detail and reported through OnError so callers can continue with the last known good snapshot, or with no DFA loaded yet on startup.

On success the returned stop function closes the underlying fsnotify watcher and waits for background goroutines to exit. Start is typically used by the CoreDNS plugin setup path before the handler is added to the serving chain.

Types

type Config

type Config struct {
	AllowlistDir    string
	DenylistDir     string
	Debounce        time.Duration
	Logger          Logger
	OnUpdate        func(allowlist Snapshot, denylist Snapshot)
	OnCompile       func(label string, duration time.Duration)
	OnError         func(label string, err error)
	MaxCompileTime  time.Duration
	MaxStates       int
	InvertAllowlist bool
	MatcherMode     matcher.Mode
}

Config configures the watcher.

type Logger

type Logger interface {
	Warnf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger is a minimal logging interface.

type Snapshot

type Snapshot struct {
	Matcher    *matcher.Matcher
	RuleCount  int
	StateCount int
	Sources    []string // rule source strings indexed by rule ID
	Patterns   []string // rule pattern strings indexed by rule ID
}

Snapshot describes one compiled filter set state.