class

Sepia::Watcher

File system watcher for Sepia objects using crystal-fswatch.

This watcher monitors file system changes in a Sepia storage directory and emits events for created, modified, or deleted objects.

Basic Usage

storage = Sepia::FileStorage.new("./data")
watcher = Sepia::Watcher.new(storage)

# Register a callback to receive events
watcher.on_change do |event|
  puts "Event: #{event.type} for #{event.object_class}:#{event.object_id}"
end

# Start watching (this is non-blocking)
watcher.start

# When done, stop watching
watcher.stop

Design Principles

This watcher uses crystal-fswatch for reliable file system monitoring:

Cross-platform support (Linux, macOS, Windows)
No hanging issues in spec environments
Clean lifecycle management
Thread-safe event handling

Path Structure

The watcher expects paths in the format: storage_path/ClassName/object_id It will parse these paths and extract the class name and object ID for each event.

Constructors

new(storage : FileStorage)

Source

Class methods

add_internal_file(path : String) : Nil

Source

internal_file?(path : String) : Bool

Class methods for internal file tracking

Source

remove_internal_file(path : String) : Nil

Source

Instance methods

callback

Alias for callback_block to match spec expectations

Source

callback_block

Callback block for event handling

event_count

Get the number of events processed (for debugging)

Source

on_change

The callback will be called for each event that occurs while the watcher is running.

watcher.on_change do |event|
  puts "Got event: #{event.type}"
end

Source

path_resolver

Path resolver for converting file paths to Sepia object information

running

Whether the watcher is currently running

running=(running : Bool)

Whether the watcher is currently running

running?

Check if the watcher is currently running

Source

start

Start watching the storage directory for changes

This method is non-blocking and returns immediately. The actual file system monitoring happens in the background.

watcher.start
puts "Watcher started, continuing with other work..."

Source

stop

Stop watching for file system changes

This stops the background monitoring.

watcher.stop
puts "Watcher stopped"

Source

storage

Storage backend being watched