e2b 0.2.0 → 0.3.0

data/lib/e2b/services/base_service.rb

@@ -4,6 +4,7 @@ require "base64"
 require "net/http"
 require "openssl"
 require "ostruct"
+require "rubygems/version"
 
 module E2B
   module Services
@@ -15,17 +16,21 @@ module E2B
     class BaseService
       # Default envd port
       ENVD_PORT = 49983
+      DEFAULT_USERNAME = "user"
+      ENVD_DEFAULT_USER_VERSION = Gem::Version.new("0.4.0")
+      ENVD_RECURSIVE_WATCH_VERSION = Gem::Version.new("0.1.4")
 
       # @param sandbox_id [String] Sandbox ID
       # @param sandbox_domain [String] Sandbox domain (e.g., "e2b.app")
       # @param api_key [String] API key for authentication
       # @param access_token [String, nil] Sandbox-specific access token
       # @param logger [Logger, nil] Optional logger
-      def initialize(sandbox_id:, sandbox_domain:, api_key:, access_token: nil, logger: nil)
+      def initialize(sandbox_id:, sandbox_domain:, api_key:, access_token: nil, envd_version: nil, logger: nil)
         @sandbox_id = sandbox_id
         @sandbox_domain = sandbox_domain
         @api_key = api_key
         @access_token = access_token
+        @envd_version = envd_version
         @logger = logger
         @envd_client = nil
       end
@@ -40,18 +45,18 @@ module E2B
       end
 
       # Perform GET request to envd
-      def envd_get(path, params: {}, timeout: 120)
-        envd_client.get(path, params: params, timeout: timeout)
+      def envd_get(path, params: {}, timeout: 120, headers: nil)
+        envd_client.get(path, params: params, timeout: timeout, headers: headers)
       end
 
       # Perform POST request to envd
-      def envd_post(path, body: nil, timeout: 120)
-        envd_client.post(path, body: body, timeout: timeout)
+      def envd_post(path, body: nil, timeout: 120, headers: nil)
+        envd_client.post(path, body: body, timeout: timeout, headers: headers)
       end
 
       # Perform DELETE request to envd
-      def envd_delete(path, timeout: 120)
-        envd_client.delete(path, timeout: timeout)
+      def envd_delete(path, timeout: 120, headers: nil)
+        envd_client.delete(path, timeout: timeout, headers: headers)
       end
 
       # Perform Connect RPC call to envd
@@ -62,8 +67,39 @@ module E2B
       # @param timeout [Integer] Request timeout in seconds
       # @param on_event [Proc, nil] Callback for streaming events
       # @return [Hash] Response with :events, :stdout, :stderr, :exit_code
-      def envd_rpc(service, method, body: {}, timeout: 120, on_event: nil)
-        envd_client.rpc(service, method, body: body, timeout: timeout, on_event: on_event)
+      def envd_rpc(service, method, body: {}, timeout: 120, on_event: nil, headers: nil)
+        envd_client.rpc(service, method, body: body, timeout: timeout, on_event: on_event, headers: headers)
+      end
+
+      def user_auth_headers(user)
+        resolved_user = resolve_username(user)
+        return nil if resolved_user.nil? || resolved_user.to_s.empty?
+
+        encoded = Base64.strict_encode64("#{resolved_user}:")
+        { "Authorization" => "Basic #{encoded}" }
+      end
+
+      def resolve_username(user)
+        return user unless user.nil? || user.to_s.empty?
+        return DEFAULT_USERNAME if legacy_default_user?
+
+        nil
+      end
+
+      def legacy_default_user?
+        return false if @envd_version.nil? || @envd_version.to_s.empty?
+
+        Gem::Version.new(@envd_version) < ENVD_DEFAULT_USER_VERSION
+      rescue ArgumentError
+        false
+      end
+
+      def supports_recursive_watch?
+        return true if @envd_version.nil? || @envd_version.to_s.empty?
+
+        Gem::Version.new(@envd_version) >= ENVD_RECURSIVE_WATCH_VERSION
+      rescue ArgumentError
+        true
       end
 
       private
@@ -98,28 +134,31 @@ module E2B
         @connection = build_connection
       end
 
-      def get(path, params: {}, timeout: DEFAULT_TIMEOUT)
+      def get(path, params: {}, timeout: DEFAULT_TIMEOUT, headers: nil)
         handle_response do
           @connection.get(normalize_path(path)) do |req|
             req.params = params
             req.options.timeout = timeout
+            req.headers.update(headers) if headers
           end
         end
       end
 
-      def post(path, body: nil, timeout: DEFAULT_TIMEOUT)
+      def post(path, body: nil, timeout: DEFAULT_TIMEOUT, headers: nil)
         handle_response do
           @connection.post(normalize_path(path)) do |req|
             req.body = body.to_json if body
             req.options.timeout = timeout
+            req.headers.update(headers) if headers
           end
         end
       end
 
-      def delete(path, timeout: DEFAULT_TIMEOUT)
+      def delete(path, timeout: DEFAULT_TIMEOUT, headers: nil)
         handle_response do
           @connection.delete(normalize_path(path)) do |req|
             req.options.timeout = timeout
+            req.headers.update(headers) if headers
           end
         end
       end
@@ -132,7 +171,7 @@ module E2B
       # @param timeout [Integer] Timeout in seconds
       # @param on_event [Proc, nil] Callback for streaming events
       # @return [Hash] Response
-      def rpc(service, method, body: {}, timeout: DEFAULT_TIMEOUT, on_event: nil)
+      def rpc(service, method, body: {}, timeout: DEFAULT_TIMEOUT, on_event: nil, headers: nil)
         path = "/#{service}/#{method}"
         json_body = body.to_json
         envelope = create_connect_envelope(json_body)
@@ -140,7 +179,7 @@ module E2B
         log_debug("RPC #{service}/#{method}")
 
         if on_event
-          return handle_streaming_rpc(path, envelope, timeout, on_event)
+          return handle_streaming_rpc(path, envelope, timeout, on_event, headers)
         end
 
         handle_rpc_response(service, method) do
@@ -152,6 +191,7 @@ module E2B
             request["Content-Type"] = "application/connect+json"
             request["X-Access-Token"] = @access_token if @access_token
             request["Connection"] = "keep-alive"
+            apply_custom_headers(request, headers)
             request.body = envelope
 
             response = http.request(request)
@@ -167,7 +207,7 @@ module E2B
       end
 
       # Streaming RPC with chunked response processing
-      def handle_streaming_rpc(path, envelope, timeout, on_event)
+      def handle_streaming_rpc(path, envelope, timeout, on_event, headers)
         result = { events: [], stdout: "", stderr: "", exit_code: nil }
         buffer = "".b
 
@@ -180,6 +220,7 @@ module E2B
           request["Content-Type"] = "application/connect+json"
           request["X-Access-Token"] = @access_token if @access_token
           request["Connection"] = "keep-alive"
+          apply_custom_headers(request, headers)
           request.body = envelope
 
           http.start do |conn|
@@ -480,6 +521,14 @@ module E2B
       def log_debug(message)
         @logger&.debug("[E2B] #{message}")
       end
+
+      def apply_custom_headers(request, headers)
+        return unless headers
+
+        headers.each do |key, value|
+          request[key] = value
+        end
+      end
     end
   end
 end

data/lib/e2b/services/command_handle.rb

@@ -4,6 +4,65 @@ require "base64"
 
 module E2B
   module Services
+    # Thread-safe buffer for live command events.
+    #
+    # Allows a producer thread to push envd events while the command handle
+    # drains them on demand from {CommandHandle#each} or {CommandHandle#wait}.
+    class LiveEventStream
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @items = []
+        @closed = false
+      end
+
+      def push(event)
+        @mutex.synchronize do
+          return if @closed
+
+          @items << [:event, event]
+          @condition.signal
+        end
+      end
+
+      def fail(error)
+        @mutex.synchronize do
+          return if @closed
+
+          @items << [:error, error]
+          @condition.signal
+        end
+      end
+
+      def close(discard_pending: false)
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          @items.clear if discard_pending
+          @condition.broadcast
+        end
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        loop do
+          item = @mutex.synchronize do
+            @condition.wait(@mutex) while @items.empty? && !@closed
+            @items.shift
+          end
+
+          break unless item
+
+          type, payload = item
+          raise payload if type == :error
+
+          yield payload
+        end
+      end
+    end
+
     # Result of a command execution in the sandbox.
     #
     # Returned by {CommandHandle#wait} when the command finishes successfully.
@@ -92,25 +151,29 @@ module E2B
       # @param pid [Integer, nil] Process ID
       # @param handle_kill [Proc] Proc that sends SIGKILL to the process
       # @param handle_send_stdin [Proc] Proc that sends data to stdin/pty
+      # @param handle_disconnect [Proc, nil] Proc that disconnects the event stream
       # @param events_proc [Proc, nil] Proc that accepts a block and yields
       #   parsed events as they arrive. Each event is a Hash with keys like
       #   "event" => { "Start" => ..., "Data" => ..., "End" => ... }.
       #   May be nil if the result is already materialized.
       # @param result [Hash, nil] Pre-materialized result from a synchronous
       #   RPC call. Expected keys: :events, :stdout, :stderr, :exit_code.
-      def initialize(pid:, handle_kill:, handle_send_stdin:, events_proc: nil, result: nil)
+      def initialize(pid:, handle_kill:, handle_send_stdin:, handle_disconnect: nil, events_proc: nil, result: nil)
         @pid = pid
         @handle_kill = handle_kill
         @handle_send_stdin = handle_send_stdin
+        @handle_disconnect = handle_disconnect
         @events_proc = events_proc
         @result = result
         @disconnected = false
         @finished = false
+        @completed = false
         @stdout = ""
         @stderr = ""
         @exit_code = nil
         @error = nil
         @mutex = Mutex.new
+        @materialized_event_index = 0
       end
 
       # Wait for the command to finish and return the result.
@@ -126,6 +189,10 @@ module E2B
       # @raise [CommandExitError] if exit code is non-zero
       def wait(on_stdout: nil, on_stderr: nil, on_pty: nil)
         consume_events(on_stdout: on_stdout, on_stderr: on_stderr, on_pty: on_pty)
+        unless @disconnected || completed?
+          raise E2BError, "Command ended without an end event"
+        end
+
         build_result.tap do |cmd_result|
           unless cmd_result.success?
             raise CommandExitError.new(
@@ -162,7 +229,10 @@ module E2B
       #
       # @return [void]
       def disconnect
+        return if @disconnected
+
         @disconnected = true
+        @handle_disconnect&.call
       end
 
       # Iterate over command output as it arrives.
@@ -201,11 +271,9 @@ module E2B
         each do |stdout_chunk, stderr_chunk, pty_chunk|
           if stdout_chunk
             on_stdout&.call(stdout_chunk)
-            @mutex.synchronize { @stdout += stdout_chunk }
           end
           if stderr_chunk
             on_stderr&.call(stderr_chunk)
-            @mutex.synchronize { @stderr += stderr_chunk }
           end
           if pty_chunk
             on_pty&.call(pty_chunk)
@@ -222,22 +290,12 @@ module E2B
       #
       # @return [CommandResult]
       def build_result
-        if @result && !@finished
-          # Use the pre-materialized result from the synchronous RPC call
-          CommandResult.new(
-            stdout: @result[:stdout] || "",
-            stderr: @result[:stderr] || "",
-            exit_code: @result[:exit_code] || 0,
-            error: @result[:error]
-          )
-        else
-          CommandResult.new(
-            stdout: @stdout,
-            stderr: @stderr,
-            exit_code: @exit_code || 0,
-            error: @error
-          )
-        end
+        CommandResult.new(
+          stdout: resolved_stdout,
+          stderr: resolved_stderr,
+          exit_code: resolved_exit_code || 0,
+          error: resolved_error
+        )
       end
 
       # Iterate over events from a pre-materialized result hash.
@@ -249,14 +307,14 @@ module E2B
       # @yield [stdout, stderr, pty]
       # @return [void]
       def iterate_materialized_events
-        events = @result[:events] || []
-        events.each do |event_hash|
+        events = result_value(:events) || []
+        while @materialized_event_index < events.length
           break if @disconnected
 
-          next unless event_hash.is_a?(Hash) && event_hash["event"]
+          event_hash = events[@materialized_event_index]
+          @materialized_event_index += 1
 
-          event = event_hash["event"]
-          process_event(event) do |stdout_chunk, stderr_chunk, pty_chunk|
+          process_message(event_hash) do |stdout_chunk, stderr_chunk, pty_chunk|
             yield stdout_chunk, stderr_chunk, pty_chunk
           end
         end
@@ -270,25 +328,58 @@ module E2B
       # @yield [stdout, stderr, pty]
       # @return [void]
       def iterate_streaming_events
-        @events_proc.call do |event_hash|
-          break if @disconnected
-
-          next unless event_hash.is_a?(Hash) && event_hash["event"]
+        catch(:stop_iteration) do
+          @events_proc.call do |event_hash|
+            throw :stop_iteration if @disconnected
 
-          event = event_hash["event"]
-          process_event(event) do |stdout_chunk, stderr_chunk, pty_chunk|
-            yield stdout_chunk, stderr_chunk, pty_chunk
+            process_message(event_hash) do |stdout_chunk, stderr_chunk, pty_chunk|
+              yield stdout_chunk, stderr_chunk, pty_chunk
+            end
           end
         end
       end
 
-      # Process a single event from the stream, extracting output data.
+      # Process a single stream message, extracting output data.
+      #
+      # Messages usually arrive with an "event" wrapper from the envd process
+      # service, but some paths also surface top-level stdout/stderr/exitCode
+      # fields. This method handles both shapes.
       #
       # Event shapes from the envd process service:
       # - Start: { "Start" => { "pid" => 123 } }
       # - Data:  { "Data"  => { "stdout" => "base64", "stderr" => "base64", "pty" => "base64" } }
       # - End:   { "End"   => { "exitCode" => 0, "error" => "...", "status" => "..." } }
       #
+      # @param message [Hash] A raw stream message
+      # @yield [stdout, stderr, pty]
+      # @return [void]
+      def process_message(message)
+        return unless message.is_a?(Hash)
+
+        event = message["event"]
+        process_event(event) { |stdout_chunk, stderr_chunk, pty_chunk| yield stdout_chunk, stderr_chunk, pty_chunk } if event.is_a?(Hash)
+
+        if event.nil?
+          stdout_chunk = decode_base64(message["stdout"])
+          stderr_chunk = decode_base64(message["stderr"])
+
+          if stdout_chunk && !stdout_chunk.empty?
+            append_stdout(stdout_chunk)
+            yield(stdout_chunk, nil, nil)
+          end
+
+          if stderr_chunk && !stderr_chunk.empty?
+            append_stderr(stderr_chunk)
+            yield(nil, stderr_chunk, nil)
+          end
+        end
+
+        exit_value = message["exitCode"] || message["exit_code"]
+        complete!(exit_value, message["error"]) if exit_value
+      end
+
+      # Process a single event from the stream, extracting output data.
+      #
       # @param event [Hash] The event sub-hash (value of "event" key)
       # @yield [stdout, stderr, pty]
       # @return [void]
@@ -300,8 +391,16 @@ module E2B
           stderr_chunk = decode_base64(data_event["stderr"])
           pty_chunk = decode_base64(data_event["pty"])
 
-          yield(stdout_chunk, nil, nil) if stdout_chunk && !stdout_chunk.empty?
-          yield(nil, stderr_chunk, nil) if stderr_chunk && !stderr_chunk.empty?
+          if stdout_chunk && !stdout_chunk.empty?
+            append_stdout(stdout_chunk)
+            yield(stdout_chunk, nil, nil)
+          end
+
+          if stderr_chunk && !stderr_chunk.empty?
+            append_stderr(stderr_chunk)
+            yield(nil, stderr_chunk, nil)
+          end
+
           yield(nil, nil, pty_chunk) if pty_chunk && !pty_chunk.empty?
         end
 
@@ -310,8 +409,62 @@ module E2B
         return unless end_event
 
         exit_value = end_event["exitCode"] || end_event["exit_code"] || end_event["status"]
-        @exit_code = parse_exit_code(exit_value)
-        @error = end_event["error"] if end_event["error"] && !end_event["error"].empty?
+        complete!(exit_value, end_event["error"])
+      end
+
+      def append_stdout(chunk)
+        @mutex.synchronize { @stdout += chunk }
+      end
+
+      def append_stderr(chunk)
+        @mutex.synchronize { @stderr += chunk }
+      end
+
+      def complete!(exit_value, error_value)
+        @mutex.synchronize do
+          @completed = true
+          @exit_code = parse_exit_code(exit_value)
+          @error = error_value if error_value && !error_value.empty?
+        end
+      end
+
+      def completed?
+        return true if @completed
+
+        !result_value(:exit_code, "exit_code", "exitCode").nil?
+      end
+
+      def resolved_stdout
+        fallback = result_value(:stdout, "stdout")
+        @stdout.empty? && fallback ? fallback : @stdout
+      end
+
+      def resolved_stderr
+        fallback = result_value(:stderr, "stderr")
+        @stderr.empty? && fallback ? fallback : @stderr
+      end
+
+      def resolved_exit_code
+        return @exit_code unless @exit_code.nil?
+
+        raw_exit_code = result_value(:exit_code, "exit_code", "exitCode")
+        return nil if raw_exit_code.nil?
+
+        parse_exit_code(raw_exit_code)
+      end
+
+      def resolved_error
+        @error || result_value(:error, "error")
+      end
+
+      def result_value(*keys)
+        return nil unless @result.is_a?(Hash)
+
+        keys.each do |key|
+          return @result[key] if @result.key?(key)
+        end
+
+        nil
       end
 
       # Decode a base64-encoded string.

data/lib/e2b/services/commands.rb

@@ -24,6 +24,7 @@ module E2B
     #   handle = sandbox.commands.run("sleep 10", background: true)
     #   handle.kill
     class Commands < BaseService
+      include LiveStreamable
       # Run a command in the sandbox
       #
       # @param cmd [String] Command to execute (run via /bin/bash -l -c)
@@ -55,8 +56,10 @@ module E2B
         process_spec[:cwd] = cwd if cwd
 
         body = { process: process_spec }
+        headers = user_auth_headers(user)
 
         # Set up streaming callback
+        stream_block = block if block_given?
         streaming_callback = nil
         if on_stdout || on_stderr || block_given?
           streaming_callback = lambda { |event_data|
@@ -66,46 +69,45 @@ module E2B
             on_stdout&.call(stdout_chunk) if stdout_chunk && !stdout_chunk.empty?
             on_stderr&.call(stderr_chunk) if stderr_chunk && !stderr_chunk.empty?
 
-            if block_given?
-              yield(:stdout, stdout_chunk) if stdout_chunk && !stdout_chunk.empty?
-              yield(:stderr, stderr_chunk) if stderr_chunk && !stderr_chunk.empty?
-            end
+            stream_block&.call(:stdout, stdout_chunk) if stdout_chunk && !stdout_chunk.empty?
+            stream_block&.call(:stderr, stderr_chunk) if stderr_chunk && !stderr_chunk.empty?
           }
         end
 
         effective_timeout = request_timeout || (timeout + 30)
 
+        if background
+          return build_live_handle(
+            rpc_method: "Start",
+            body: body,
+            timeout: effective_timeout,
+            headers: headers,
+            on_stdout: on_stdout,
+            on_stderr: on_stderr,
+            &block
+          )
+        end
+
         response = envd_rpc("process.Process", "Start",
           body: body,
           timeout: effective_timeout,
+          headers: headers,
           on_event: streaming_callback)
 
-        pid = extract_pid(response)
+        # Return CommandResult for foreground processes
+        result = build_result(response)
 
-        if background
-          # Return a CommandHandle for background processes
-          CommandHandle.new(
-            pid: pid,
-            handle_kill: -> { kill(pid) },
-            handle_send_stdin: ->(data) { send_stdin(pid, data) },
-            result: response
+        # Raise on non-zero exit code (matching official SDK behavior)
+        if result.exit_code != 0
+          raise CommandExitError.new(
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exit_code: result.exit_code,
+            error: result.error
           )
-        else
-          # Return CommandResult for foreground processes
-          result = build_result(response)
-
-          # Raise on non-zero exit code (matching official SDK behavior)
-          if result.exit_code != 0
-            raise CommandExitError.new(
-              stdout: result.stdout,
-              stderr: result.stderr,
-              exit_code: result.exit_code,
-              error: result.error
-            )
-          end
-
-          result
         end
+
+        result
       end
 
       # List running processes
@@ -133,12 +135,13 @@ module E2B
       # @param pid [Integer] Process ID to kill
       # @param request_timeout [Integer, nil] Request timeout in seconds
       # @return [Boolean] true if killed, false if not found
-      def kill(pid, request_timeout: nil)
+      def kill(pid, request_timeout: nil, headers: nil)
         envd_rpc("process.Process", "SendSignal",
           body: {
             process: { pid: pid },
             signal: 9 # SIGKILL
           },
+          headers: headers,
           timeout: request_timeout || 30)
         true
       rescue E2B::NotFoundError
@@ -152,13 +155,14 @@ module E2B
       # @param pid [Integer] Process ID
       # @param data [String] Data to send to stdin
       # @param request_timeout [Integer, nil] Request timeout in seconds
-      def send_stdin(pid, data, request_timeout: nil)
+      def send_stdin(pid, data, request_timeout: nil, headers: nil)
         encoded = Base64.strict_encode64(data.to_s)
         envd_rpc("process.Process", "SendInput",
           body: {
             process: { pid: pid },
             input: { stdin: encoded }
           },
+          headers: headers,
           timeout: request_timeout || 30)
       end
 
@@ -169,33 +173,16 @@ module E2B
       # @param request_timeout [Integer, nil] Request timeout in seconds
       # @return [CommandHandle] Handle for the connected process
       def connect(pid, timeout: 60, request_timeout: nil)
-        response = envd_rpc("process.Process", "Connect",
+        build_live_handle(
+          rpc_method: "Connect",
           body: { process: { pid: pid } },
-          timeout: request_timeout || (timeout + 30))
-
-        CommandHandle.new(
-          pid: pid,
-          handle_kill: -> { kill(pid) },
-          handle_send_stdin: ->(data) { send_stdin(pid, data) },
-          result: response
+          headers: user_auth_headers(nil),
+          timeout: request_timeout || (timeout + 30)
         )
       end
 
       private
 
-      # Extract PID from streaming response events
-      def extract_pid(response)
-        events = response[:events] || []
-        events.each do |event|
-          next unless event.is_a?(Hash) && event["event"]
-          start_event = event["event"]["Start"] || event["event"]["start"]
-          if start_event && start_event["pid"]
-            return start_event["pid"].to_i
-          end
-        end
-        nil
-      end
-
       # Build CommandResult from response
       def build_result(response)
         stdout = response[:stdout] || ""