File System Watching

Sepia's file system watcher enables reactive applications that respond to external changes in storage. It's particularly useful for collaborative applications where multiple users or processes might modify data simultaneously.

Platform Behavior

The watcher implementation is selected automatically at compile time:

  • Linux — uses kernel inotify (via inotify.cr) for efficient, recursive monitoring. No external dependencies.
  • Other platforms (macOS, Windows) — a no-op watcher with a compatible API. Callbacks can be registered but are never fired, so code that uses the watcher compiles and runs everywhere.

No compile-time flags or manual backend selection are needed.

Usage

storage = Sepia::Storage.backend.as(Sepia::FileStorage)
watcher = Sepia::Watcher.new(storage)

watcher.on_change do |event|
  puts "#{event.type} #{event.object_class}/#{event.object_id}"

  # Optionally load the changed object directly
  if doc = event.object(Document)
    puts "  now at generation #{doc.generation}"
  end
end

watcher.start

Call watcher.stop when you're done watching.

Events

Each Sepia::Watcher::Event provides:

  • type — EventType::Created, Modified, or Deleted
  • object_class and object_id — identity of the affected object
  • path — full path on disk
  • object_info — resolved PathResolver::ObjectInfo (see Utilities)
  • object(klass) — convenience method to load the changed object

Internal Changes Are Filtered

Sepia's own writes (event log files, temporary files from atomic saves) are tracked and filtered out, so you only see changes to actual objects — including changes made by other processes sharing the same storage.

Notes

  • The watcher monitors the entire storage tree recursively.
  • Hidden files (paths starting with .) are ignored.
  • Events automatically invalidate the in-process object cache, so subsequent loads see fresh data.