autoswap

README

autoswap

Automatically hot-swap in-memory values from files.

Documentation

Overview

Package autoswap provides a generic hot-reloader for file- or directory-based resources. It watches filesystem changes, detects content updates via a SHA-256 hash, and atomically swaps in new parsed values of an arbitrary type T. It supports debounced file events, versioning, and user-defined hooks.

Index

• type Hooks
• type LoaderFunc
• type Watcher
  • func New[T any](fsys fs.FS, path, label string, loader LoaderFunc[T], hooks Hooks[T]) *Watcher[T]
  • func NewDirWatcher[T any](fsys fs.FS, dir, label string, loader LoaderFunc[T], hooks Hooks[T]) *Watcher[T]
  • func (w *Watcher[T]) Load() *T
  • func (w *Watcher[T]) Start(ctx context.Context) error
  • func (w *Watcher[T]) Sync() error
  • func (w *Watcher[T]) Version() uint64
  • func (w *Watcher[T]) Watch(ctx context.Context) error

Types

type Hooks

type Hooks[T any] struct {
	OnUpdate func(value *T)
	OnError  func(err error)
}

Hooks groups user-defined callbacks for successful updates or errors. OnUpdate is invoked with the new value after each successful reload. OnError is invoked with the error encountered during TryUpdate or Start.

type LoaderFunc

type LoaderFunc[T any] func(files map[string][]byte) (*T, error)

LoaderFunc is a user-supplied function that parses raw filesystem contents into a value of type T. The files map keys are relative paths within the watched filesystem and values are the corresponding file byte contents. LoaderFunc should return the parsed value or an error if parsing fails.

type Watcher

type Watcher[T any] struct {
	// contains filtered or unexported fields
}

Watcher monitors a file or directory and reloads values of type T when changes occur. It uses an atomic pointer for safe concurrent access, a SHA-256 hash to detect content changes, and an optional debounce period to coalesce rapid filesystem events.

func New

func New[T any](fsys fs.FS, path, label string, loader LoaderFunc[T], hooks Hooks[T]) *Watcher[T]

New constructs a Watcher for a single file. fsys is the filesystem to read from (e.g., os.DirFS("/")); path is the file path to watch; label is used in logs; loader parses file contents into *T; hooks define optional OnUpdate and OnError callbacks.

func NewDirWatcher

func NewDirWatcher[T any](fsys fs.FS, dir, label string, loader LoaderFunc[T], hooks Hooks[T]) *Watcher[T]

NewDirWatcher constructs a Watcher for all files under a directory. fsys is the base filesystem; dir is the directory path to watch; label is used in logs; loader parses the collected files map into *T; hooks define callbacks. It scopes the FS via fs.Sub if supported.

func (*Watcher[T]) Load

func (w *Watcher[T]) Load() *T

Load returns the most recently loaded value of type T, or nil if not loaded. Safe for concurrent use.

func (*Watcher[T]) Start

func (w *Watcher[T]) Start(ctx context.Context) error

Start performs an initial TryUpdate and then begins watching for changes. Returns any error from the initial load or watcher setup.

func (*Watcher[T]) Sync

func (w *Watcher[T]) Sync() error

Sync forces a reload: it reads the watched file or directory, computes a combined SHA-256 hash, and if the hash differs from the previous version, parses new content via the loader, updates the value, increments the version, and invokes OnUpdate. If an error occurs, OnError is invoked. Returns any I/O or parsing error.

func (*Watcher[T]) Version

func (w *Watcher[T]) Version() uint64

Version returns a monotonically increasing counter that increments on each successful reload. Useful for cache invalidation or change tracking.

func (*Watcher[T]) Watch

func (w *Watcher[T]) Watch(ctx context.Context) error

Watch begins monitoring the file or directory and triggers TryUpdate() after a debounce delay when relevant events occur. The watcher runs in a background goroutine and stops when ctx is cancelled. Returns an error if the internal file watcher cannot be created or initialized.