Class: E2B::Services::WatchHandle

Inherits:
Object
  • Object
show all
Defined in:
lib/e2b/services/watch_handle.rb

Overview

Handle for watching directory changes in the sandbox

Returned by Filesystem#watch_dir. Uses the polling-based watcher RPCs (CreateWatcher/GetWatcherEvents/RemoveWatcher) from the filesystem proto service.

The watcher is created externally and its ID is passed into this handle. Call #get_new_events to poll for new filesystem changes, and #stop to clean up the watcher when done.

Examples:

Basic usage

handle = sandbox.files.watch_dir("/home/user/project")
loop do
  events = handle.get_new_events
  events.each { |e| puts "#{e.name}: #{e.type}" }
  sleep 1
end
handle.stop

With ensure block for cleanup

handle = sandbox.files.watch_dir("/home/user/project")
begin
  events = handle.get_new_events
  events.each { |e| process_event(e) }
ensure
  handle.stop
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(watcher_id:, envd_rpc_proc:, headers: nil) ⇒ WatchHandle

Create a new WatchHandle

Parameters:

  • watcher_id (String) —

    The watcher ID returned by the CreateWatcher RPC

  • envd_rpc_proc (Proc) —

    A callable that performs RPC calls. It must accept three positional arguments (service, method) and keyword arguments (body:, timeout:). Typically a lambda wrapping BaseService#envd_rpc.



41
42
43
44
45
46
 
# File 'lib/e2b/services/watch_handle.rb', line 41

def initialize(watcher_id:, envd_rpc_proc:, headers: nil)
  @watcher_id = watcher_id
  @envd_rpc_proc = envd_rpc_proc
  @headers = headers
  @stopped = false
end

Instance Attribute Details

#watcher_id ⇒ String (readonly)

Returns The watcher ID assigned by the CreateWatcher RPC.

Returns:

  • (String) —

    The watcher ID assigned by the CreateWatcher RPC



33
34
35
 
# File 'lib/e2b/services/watch_handle.rb', line 33

def watcher_id
  @watcher_id
end

Instance Method Details

#get_new_events ⇒ Array<Models::FilesystemEvent>

Poll for new filesystem events since the last check

Calls the GetWatcherEvents RPC to retrieve any filesystem events that have occurred since the last poll (or since the watcher was created).

Returns:

Raises:



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/e2b/services/watch_handle.rb', line 55

def get_new_events
  raise E2B::E2BError, "Watcher has been stopped" if @stopped

  response = @envd_rpc_proc.call(
    "filesystem.Filesystem", "GetWatcherEvents",
    body: { watcherId: @watcher_id },
    headers: @headers
  )

  events = extract_events(response)
  events.map { |e| Models::FilesystemEvent.from_hash(e) }
end

#stop ⇒ void

This method returns an undefined value.

Stop watching and clean up the watcher

Calls the RemoveWatcher RPC to release server-side resources. After calling this method, #get_new_events will raise an error. Calling stop on an already-stopped handle is a no-op.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/e2b/services/watch_handle.rb', line 75

def stop
  return if @stopped

  @envd_rpc_proc.call(
    "filesystem.Filesystem", "RemoveWatcher",
    body: { watcherId: @watcher_id },
    headers: @headers
  )
  @stopped = true
rescue StandardError
  @stopped = true
  # Ignore errors on cleanup - the watcher may have already been
  # removed server-side (e.g., sandbox shutdown)
end

#stopped? ⇒ Boolean

Check if the watcher has been stopped

Returns:

  • (Boolean) —

    true if #stop has been called



93
94
95
 
# File 'lib/e2b/services/watch_handle.rb', line 93

def stopped?
  @stopped
end