Documentation
¶
Overview ¶
Package state provides state tracking and persistence.
Index ¶
- Constants
- Variables
- type FileChange
- type FileState
- type FileSystemStore
- func (s *FileSystemStore) CaptureFile(path string) (*FileState, error)
- func (s *FileSystemStore) CaptureFileWithContent(path string) (*FileState, error)
- func (s *FileSystemStore) CaptureFileWithContext(ctx context.Context, path string) (*FileState, error)
- func (s *FileSystemStore) Clear()
- func (s *FileSystemStore) CreateSnapshot(message string) *Snapshot
- func (s *FileSystemStore) DetectChanges() ([]*FileChange, error)
- func (s *FileSystemStore) GetChanges() []*FileChange
- func (s *FileSystemStore) GetChangesSince(snapshotID string) []*FileChange
- func (s *FileSystemStore) GetSnapshot(id string) *Snapshot
- func (s *FileSystemStore) ListSnapshots() []*Snapshot
- func (s *FileSystemStore) RecordChange(path string, changeType string) error
- func (s *FileSystemStore) Rollback(snapshotID string) error
- func (s *FileSystemStore) RollbackChanges(count int) error
- func (s *FileSystemStore) Track(path string) error
- func (s *FileSystemStore) TrackDir(dir string, patterns ...string) error
- type FileSystemStoreOption
- type FileWatcher
- type Snapshot
- type WatchConfig
Constants ¶
const ( // DefaultWatchDebounce is the default debounce duration for file watch events. // Multiple rapid events are coalesced into a single change notification. DefaultWatchDebounce = 100 * time.Millisecond // DefaultStopTimeout is the maximum time to wait for the event loop to exit. DefaultStopTimeout = 5 * time.Second )
File watcher defaults.
Variables ¶
var ( ErrPathOutsideBase = pathutil.ErrPathOutsideBase ErrPathTraversal = pathutil.ErrPathTraversal )
Security-related errors.
var ( // ErrWatcherAlreadyRunning is returned when StartWithContext is called on a running watcher. ErrWatcherAlreadyRunning = fmt.Errorf("file watcher is already running") // ErrStopTimeout is returned when Stop fails to terminate the goroutine within the timeout. ErrStopTimeout = fmt.Errorf("file watcher stop timed out") )
FileWatcher errors.
Functions ¶
This section is empty.
Types ¶
type FileChange ¶
type FileChange struct {
Path string `json:"path"`
ChangeType string `json:"change_type"` // "create", "modify", "delete"
Before *FileState `json:"before,omitempty"`
After *FileState `json:"after,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
FileChange represents a change to a file.
type FileState ¶
type FileState struct {
Path string `json:"path"`
Hash string `json:"hash"`
Size int64 `json:"size"`
ModTime time.Time `json:"mod_time"`
Mode os.FileMode `json:"mode"`
Exists bool `json:"exists"`
Content []byte `json:"-"` // Not serialized by default
}
FileState represents the state of a file at a point in time.
type FileSystemStore ¶
type FileSystemStore struct {
// contains filtered or unexported fields
}
FileSystemStore tracks file system state and changes.
func NewFileSystemStore ¶
func NewFileSystemStore(basePath string, opts ...FileSystemStoreOption) *FileSystemStore
NewFileSystemStore creates a new file system store with optional path enforcement.
func (*FileSystemStore) CaptureFile ¶
func (s *FileSystemStore) CaptureFile(path string) (*FileState, error)
CaptureFile captures the current state of a file. This is the public API that handles path validation.
func (*FileSystemStore) CaptureFileWithContent ¶
func (s *FileSystemStore) CaptureFileWithContent(path string) (*FileState, error)
CaptureFileWithContent captures state including file content.
func (*FileSystemStore) CaptureFileWithContext ¶ added in v0.3.0
func (s *FileSystemStore) CaptureFileWithContext(ctx context.Context, path string) (*FileState, error)
CaptureFileWithContext captures the current state of a file with context cancellation. This is the public API that handles path validation and respects context cancellation.
func (*FileSystemStore) CreateSnapshot ¶
func (s *FileSystemStore) CreateSnapshot(message string) *Snapshot
CreateSnapshot creates a snapshot of current tracked files.
func (*FileSystemStore) DetectChanges ¶
func (s *FileSystemStore) DetectChanges() ([]*FileChange, error)
DetectChanges checks for changes since tracking started.
func (*FileSystemStore) GetChanges ¶
func (s *FileSystemStore) GetChanges() []*FileChange
GetChanges returns recorded changes.
func (*FileSystemStore) GetChangesSince ¶
func (s *FileSystemStore) GetChangesSince(snapshotID string) []*FileChange
GetChangesSince returns changes since a snapshot.
func (*FileSystemStore) GetSnapshot ¶
func (s *FileSystemStore) GetSnapshot(id string) *Snapshot
GetSnapshot retrieves a snapshot by ID.
func (*FileSystemStore) ListSnapshots ¶
func (s *FileSystemStore) ListSnapshots() []*Snapshot
ListSnapshots returns all snapshots.
func (*FileSystemStore) RecordChange ¶
func (s *FileSystemStore) RecordChange(path string, changeType string) error
RecordChange manually records a file change.
func (*FileSystemStore) Rollback ¶
func (s *FileSystemStore) Rollback(snapshotID string) error
Rollback restores files to a previous snapshot.
func (*FileSystemStore) RollbackChanges ¶
func (s *FileSystemStore) RollbackChanges(count int) error
RollbackChanges undoes recent changes.
func (*FileSystemStore) Track ¶
func (s *FileSystemStore) Track(path string) error
Track starts tracking a file for changes.
type FileSystemStoreOption ¶
type FileSystemStoreOption func(*FileSystemStore)
FileSystemStoreOption configures FileSystemStore.
func WithEnforceBasePath ¶
func WithEnforceBasePath(enforce bool) FileSystemStoreOption
WithEnforceBasePath enables strict base path enforcement for all operations.
func WithMaxChanges ¶
func WithMaxChanges(max int) FileSystemStoreOption
WithMaxChanges limits the number of changes tracked (oldest evicted first).
func WithMaxSnapshots ¶
func WithMaxSnapshots(max int) FileSystemStoreOption
WithMaxSnapshots limits the number of snapshots kept (oldest evicted first).
type FileWatcher ¶
type FileWatcher struct {
// contains filtered or unexported fields
}
FileWatcher watches files for changes using fsnotify. This provides event-driven file watching that scales to >10k files without the CPU overhead of polling.
func NewFileWatcher ¶
func NewFileWatcher(config *WatchConfig, store *FileSystemStore) *FileWatcher
NewFileWatcher creates a file watcher.
func (*FileWatcher) OnChange ¶
func (w *FileWatcher) OnChange(fn func([]*FileChange)) *FileWatcher
OnChange sets the callback for file changes. Must be called before Start() or behavior is undefined.
func (*FileWatcher) OnError ¶
func (w *FileWatcher) OnError(fn func(error)) *FileWatcher
OnError sets the callback for watcher errors. If not set, errors are logged to stderr. Must be called before Start() or behavior is undefined.
func (*FileWatcher) Start ¶
func (w *FileWatcher) Start() error
Start begins watching for changes. Deprecated: Use StartWithContext for proper context cancellation support.
func (*FileWatcher) StartWithContext ¶ added in v0.3.0
func (w *FileWatcher) StartWithContext(ctx context.Context) error
StartWithContext begins watching for changes with context cancellation support. The watcher will stop when the context is cancelled. Returns ErrWatcherAlreadyRunning if the watcher is already running.
func (*FileWatcher) Stop ¶
func (w *FileWatcher) Stop() error
Stop stops watching and cleans up resources. Blocks until the event loop goroutine exits or the timeout expires. Returns ErrStopTimeout if the goroutine doesn't exit within DefaultStopTimeout.
Source Files