watcher

View on pkg.go.dev

watcher

import "github.com/thesimonho/warden/watcher"

Package watcher provides generic file-watching primitives with zero internal module dependencies. Agent-specific parsers live in agent/<name>/; this package handles only the I/O mechanics of discovering and tailing files.

Index

• Constants
• type FileTailer
  • func NewFileTailer(cfg TailerConfig) *FileTailer
  • func (t *FileTailer) Start(ctx context.Context)
  • func (t *FileTailer) Stop()
• type OffsetStore
• type TailerConfig

Constants

DefaultPollInterval is how often the tailer checks for new lines and discovers new files when no custom interval is specified.

const DefaultPollInterval = 2 * time.Second

type FileTailer

FileTailer monitors files for new lines appended over time. Files are discovered via a pluggable Discover function and tailed from the last stored offset (or the start if no offset exists).

All file I/O runs in a single goroutine to minimize wake-ups and goroutine count. With N files, the tailer uses 1 goroutine instead of N+1.

Lifecycle: single-use. Call Start once to begin watching, Stop once to shut down. Do not call Start again after Stop.

type FileTailer struct {
    // contains filtered or unexported fields
}

func NewFileTailer

func NewFileTailer(cfg TailerConfig) *FileTailer

NewFileTailer creates a tailer with the given configuration. The Discover and OnLine callbacks are required.

func (*FileTailer) Start

func (t *FileTailer) Start(ctx context.Context)

Start begins discovering and tailing files. It processes any existing files immediately, then polls for new files and new lines at the configured interval. Call Stop to shut down.

func (*FileTailer) Stop

func (t *FileTailer) Stop()

Stop signals the tailer to stop and waits for all goroutines to finish.

type OffsetStore

OffsetStore persists byte offsets for tailed files so the tailer can resume from where it left off after a restart. Implementations must be safe for concurrent use.

type OffsetStore interface {
    // LoadOffset returns the stored byte offset for a file, or 0 if no
    // offset has been stored.
    LoadOffset(projectID, agentType, filePath string) (int64, error)

    // SaveOffset persists the byte offset for a file (upsert).
    SaveOffset(projectID, agentType, filePath string, offset int64) error

    // DeleteOffset removes the stored offset for a single file.
    DeleteOffset(projectID, agentType, filePath string) error

    // DeleteOffsets removes all stored offsets for a project+agent pair.
    DeleteOffsets(projectID, agentType string) error
}

type TailerConfig

TailerConfig configures a FileTailer.

type TailerConfig struct {
    // Discover returns the current list of file paths to tail.
    // Called periodically to pick up new files (e.g. new sessions).
    Discover func() []string

    // OnLine is called for each complete line read from a tailed file.
    // The path identifies which file the line came from.
    OnLine func(path string, line []byte)

    // PollInterval controls how often the tailer checks for new lines
    // and re-discovers files. Defaults to 2s if zero.
    PollInterval time.Duration

    // Logger is the structured logger. Defaults to slog.Default() if nil.
    Logger *slog.Logger

    // OffsetStore persists byte offsets so the tailer can resume from
    // where it left off after a restart. Nil means read from byte 0.
    OffsetStore OffsetStore

    // ProjectID identifies the project for offset storage.
    ProjectID string

    // AgentType identifies the agent type for offset storage.
    AgentType string
}

Generated by gomarkdoc