puppeteer-bidi 0.0.1.beta1

data/lib/puppeteer/bidi/connection.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/promise'
+
+module Puppeteer
+  module Bidi
+    # Connection manages BiDi protocol communication
+    # Handles command sending, response waiting, and event dispatching
+    class Connection
+      class TimeoutError < Error; end
+      class ProtocolError < Error; end
+
+      DEFAULT_TIMEOUT = 30_000 # 30 seconds in milliseconds
+
+      def initialize(transport)
+        @transport = transport
+        @next_id = 1
+        @pending_commands = {}
+        @event_listeners = {}
+        @closed = false
+
+        setup_transport_handlers
+      end
+
+      # Send a BiDi command and wait for response
+      # @param method [String] BiDi method name (e.g., 'browsingContext.navigate')
+      # @param params [Hash] Command parameters
+      # @param timeout [Integer] Timeout in milliseconds
+      # @return [Hash] Command result
+      def async_send_command(method, params = {}, timeout: DEFAULT_TIMEOUT)
+        raise ProtocolError, 'Connection is closed' if @closed
+
+        id = next_id
+        command = {
+          id: id,
+          method: method,
+          params: params
+        }
+
+        # Create promise for this command
+        promise = Async::Promise.new
+
+        @pending_commands[id] = {
+          promise: promise,
+          method: method,
+          sent_at: Time.now
+        }
+
+        # Debug output
+        if ENV['DEBUG_BIDI_COMMAND']
+          puts "[BiDi] Request #{method}: #{command.inspect}"
+        end
+
+        Async do
+          # Send command through transport
+          @transport.async_send_message(command).wait
+
+          # Wait for response with timeout
+          begin
+            result = AsyncUtils.async_timeout(timeout, promise).wait
+
+            # Debug output
+            if ENV['DEBUG_BIDI_COMMAND']
+              puts "[BiDi] Response for #{method}: #{result.inspect}"
+            end
+
+            if result['error']
+              # BiDi error format: { "error": "error_type", "message": "detailed message", ... }
+              error_type = result['error']
+              error_message = result['message'] || error_type
+              raise ProtocolError, "BiDi error (#{method}): #{error_message}"
+            end
+
+            result['result']
+          rescue Async::TimeoutError
+            @pending_commands.delete(id)
+            raise TimeoutError, "Timeout waiting for #{method} (#{timeout}ms)"
+          end
+        end
+      end
+
+      # Subscribe to BiDi events
+      # @param event [String] Event name (e.g., 'browsingContext.navigationStarted')
+      # @param block [Proc] Event handler
+      def on(event, &block)
+        @event_listeners[event] ||= []
+        @event_listeners[event] << block
+      end
+
+      # Unsubscribe from BiDi events
+      def off(event, &block)
+        return unless @event_listeners[event]
+
+        if block
+          @event_listeners[event].delete(block)
+        else
+          @event_listeners.delete(event)
+        end
+      end
+
+      # Close the connection
+      def close
+        return if @closed
+
+        @closed = true
+
+        # Reject all pending commands
+        @pending_commands.each_value do |pending|
+          pending[:promise].reject(ProtocolError.new('Connection closed'))
+        end
+        @pending_commands.clear
+
+        @transport.close
+      end
+
+      def closed?
+        @closed
+      end
+
+      private
+
+      def next_id
+        id = @next_id
+        @next_id += 1
+        id
+      end
+
+      def setup_transport_handlers
+        @transport.on_message do |message|
+          handle_message(message)
+        end
+
+        @transport.on_close do
+          close
+        end
+      end
+
+      def handle_message(message)
+        # Response to a command (has 'id' field)
+        if message['id']
+          handle_response(message)
+        # Event (has 'method' but no 'id')
+        elsif message['method']
+          handle_event(message)
+        else
+          warn "Unknown BiDi message format: #{message}"
+        end
+      end
+
+      def handle_response(message)
+        id = message['id']
+        pending = @pending_commands.delete(id)
+
+        unless pending
+          warn "Received response for unknown command id: #{id}"
+          return
+        end
+
+        # Resolve the promise with the response
+        pending[:promise].resolve(message)
+      end
+
+      def handle_event(message)
+        method = message['method']
+        params = message['params'] || {}
+
+        listeners = @event_listeners[method]
+        return unless listeners
+
+        # Call all registered listeners for this event
+        listeners.each do |listener|
+          begin
+            listener.call(params)
+          rescue => e
+            warn "Error in event listener for #{method}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puppeteer/bidi/core/README.md

@@ -0,0 +1,169 @@
+# Puppeteer BiDi Core
+
+The `core` module provides a low-level layer that sits above the WebSocket transport to provide a structured API to WebDriver BiDi's flat API. It provides object-oriented semantics around WebDriver BiDi resources and automatically carries out the correct order of events through the use of events.
+
+This implementation is a Ruby port of Puppeteer's BiDi core layer, following the same design principles.
+
+## Design Principles
+
+The following design decisions should be considered when developing or using the core layer:
+
+### 1. Required vs Optional Arguments
+
+- **Required arguments** are method parameters
+- **Optional arguments** are keyword arguments
+
+This follows Ruby conventions and makes required parameters explicit.
+
+```ruby
+# Required parameter first, optional as keyword arguments
+browsing_context.navigate(url, wait: 'complete')
+```
+
+### 2. Session Visibility
+
+- The session shall **never be exposed** on any public method except on Browser
+- Private access to session is allowed
+
+This prevents obfuscation of the session's origin. By only allowing it on the browser, the origin is well-defined.
+
+### 3. WebDriver BiDi Compliance
+
+- `core` implements WebDriver BiDi plus its surrounding specifications
+- Always follow the spec, not Puppeteer's needs
+- This allows precise bug identification (spec issue vs implementation issue)
+
+### 4. Comprehensive but Minimal
+
+- Implements all edges and nodes required by a feature
+- Never skips intermediate nodes or composes edges
+- Ensures WebDriver BiDi semantics are carried out correctly
+
+Example: Fragment navigation must flow through Navigation to BrowsingContext, not directly from fragment navigation to BrowsingContext.
+
+## Architecture
+
+The core module provides these main classes:
+
+### Foundation Classes
+
+- **EventEmitter**: Event subscription and emission
+- **Disposable**: Resource management and cleanup with DisposableStack
+
+### Protocol Classes
+
+- **Session**: BiDi session management, wraps Connection
+- **Browser**: Browser instance management
+- **UserContext**: Isolated browsing contexts (similar to incognito)
+- **BrowsingContext**: Individual tabs/windows/frames
+- **Navigation**: Navigation tracking and lifecycle
+- **Request**: Network request management
+- **UserPrompt**: User prompt (alert/confirm/prompt) handling
+
+### Execution Context Classes
+
+- **Realm**: Base class for JavaScript execution contexts
+  - **WindowRealm**: Window/iframe realms
+  - **DedicatedWorkerRealm**: Dedicated worker realms
+  - **SharedWorkerRealm**: Shared worker realms
+
+## Object Hierarchy
+
+```
+Browser
+├── Session (wrapped Connection)
+└── UserContext (isolated session)
+    └── BrowsingContext (tab/window/frame)
+        ├── Navigation (navigation lifecycle)
+        ├── Request (network requests)
+        ├── UserPrompt (alerts, confirms, prompts)
+        └── Realm (JavaScript execution)
+            ├── WindowRealm (main window/iframe)
+            ├── DedicatedWorkerRealm (web workers)
+            └── SharedWorkerRealm (shared workers)
+```
+
+## Usage Example
+
+```ruby
+require 'puppeteer/bidi/core'
+
+# Create a session from an existing connection
+session = Puppeteer::Bidi::Core::Session.from(connection, capabilities)
+
+# Create a browser instance
+browser = Puppeteer::Bidi::Core::Browser.from(session)
+
+# Get the default user context
+context = browser.default_user_context
+
+# Create a browsing context (tab)
+browsing_context = context.create_browsing_context('tab')
+
+# Listen for navigation events
+browsing_context.on(:navigation) do |data|
+  navigation = data[:navigation]
+  puts "Navigation started to #{browsing_context.url}"
+end
+
+# Navigate to a URL
+browsing_context.navigate('https://example.com', wait: 'complete')
+
+# Evaluate JavaScript in the default realm
+result = browsing_context.default_realm.evaluate('document.title', true)
+puts "Page title: #{result['value']}"
+
+# Close the browsing context
+browsing_context.close
+```
+
+## Event Handling
+
+All core classes extend `EventEmitter` and emit various events:
+
+```ruby
+# Browser events
+browser.on(:closed) { |data| puts "Browser closed: #{data[:reason]}" }
+browser.on(:disconnected) { |data| puts "Browser disconnected: #{data[:reason]}" }
+
+# BrowsingContext events
+browsing_context.on(:navigation) { |data| puts "Navigation: #{data[:navigation]}" }
+browsing_context.on(:request) { |data| puts "Request: #{data[:request].url}" }
+browsing_context.on(:load) { puts "Page loaded" }
+browsing_context.on(:dom_content_loaded) { puts "DOM ready" }
+
+# Request events
+request.on(:redirect) { |redirect| puts "Redirected to: #{redirect.url}" }
+request.on(:success) { |response| puts "Response: #{response['status']}" }
+request.on(:error) { |error| puts "Request failed: #{error}" }
+```
+
+## Resource Management
+
+Core classes implement the `Disposable` pattern for proper resource cleanup:
+
+```ruby
+# Resources are automatically disposed when parent is disposed
+browser.close  # Disposes all user contexts, browsing contexts, etc.
+
+# Disposal triggers appropriate events
+browsing_context.on(:closed) do |data|
+  puts "Context closed: #{data[:reason]}"
+end
+
+# Check disposal status
+puts "Disposed: #{browsing_context.disposed?}"
+```
+
+## Differences from TypeScript Implementation
+
+1. **Ruby Conventions**: Uses snake_case instead of camelCase
+2. **Keyword Arguments**: Uses Ruby keyword arguments instead of options hashes
+3. **Symbols**: Uses symbols for event names instead of strings
+4. **No Decorators**: Decorators like `@throwIfDisposed` are implemented as method guards
+5. **Async Primitives**: Uses Ruby's Async library (Fiber-based) instead of JavaScript promises (similar to async/await)
+
+## References
+
+- [WebDriver BiDi Specification](https://w3c.github.io/webdriver-bidi/)
+- [Puppeteer BiDi Core (TypeScript)](https://github.com/puppeteer/puppeteer/tree/main/packages/puppeteer-core/src/bidi/core)

data/lib/puppeteer/bidi/core/browser.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Puppeteer
+  module Bidi
+    module Core
+      # Browser represents the browser instance in the core layer
+      # It manages user contexts and provides browser-level operations
+      class Browser < EventEmitter
+        include Disposable::DisposableMixin
+
+        # Create a browser instance from a session
+        # @param session [Session] BiDi session
+        # @return [Browser] Browser instance
+        def self.from(session)
+          browser = new(session)
+          Async do
+            browser.send(:initialize_browser).wait
+            browser
+          end
+        end
+
+        attr_reader :session
+
+        def initialize(session)
+          super()
+          @session = session
+          @closed = false
+          @reason = nil
+          @disposables = Disposable::DisposableStack.new
+          @user_contexts = {}
+          @shared_workers = {}
+        end
+
+        # Check if the browser is closed
+        def closed?
+          @closed
+        end
+
+        # Check if the browser is disconnected
+        def disconnected?
+          !@reason.nil?
+        end
+
+        alias disposed? disconnected?
+
+        # Get the default user context
+        # @return [UserContext] Default user context
+        def default_user_context
+          @user_contexts[UserContext::DEFAULT]
+        end
+
+        # Get all user contexts
+        # @return [Array<UserContext>] All user contexts
+        def user_contexts
+          @user_contexts.values
+        end
+
+        # Close the browser
+        def close
+          Async do
+            return if @closed
+
+            begin
+              @session.async_send_command('browser.close', {})
+            ensure
+              dispose_browser('Browser closed', closed: true)
+            end
+          end
+        end
+
+        # Add a preload script to the browser
+        # @param function_declaration [String] JavaScript function to preload
+        # @param options [Hash] Preload script options
+        # @option options [Array<BrowsingContext>] :contexts Contexts to apply to
+        # @option options [String] :sandbox Sandbox name
+        # @return [String] Script ID
+        def add_preload_script(function_declaration, **options)
+          raise BrowserDisconnectedError, @reason if disconnected?
+
+          params = { functionDeclaration: function_declaration }
+          if options[:contexts]
+            params[:contexts] = options[:contexts].map(&:id)
+          end
+          params[:sandbox] = options[:sandbox] if options[:sandbox]
+
+          Async do
+            result = @session.async_send_command('script.addPreloadScript', params).wait
+            result['script']
+          end
+        end
+
+        # Remove a preload script
+        # @param script [String] Script ID
+        def remove_preload_script(script)
+          raise BrowserDisconnectedError, @reason if disconnected?
+          @session.async_send_command('script.removePreloadScript', { script: script })
+        end
+
+        # Create a new user context
+        # @param options [Hash] User context options
+        # @option options [Hash] :proxy Proxy configuration
+        # @return [UserContext] New user context
+        def create_user_context(**options)
+          raise BrowserDisconnectedError, @reason if disconnected?
+
+          params = {}
+          if options[:proxy_server]
+            params[:proxy] = {
+              proxyType: 'manual',
+              httpProxy: options[:proxy_server],
+              sslProxy: options[:proxy_server],
+              noProxy: options[:proxy_bypass_list]
+            }.compact
+          end
+
+          Async do
+            result = @session.async_send_command('browser.createUserContext', params).wait
+            user_context_id = result['userContext']
+
+            create_user_context_object(user_context_id)
+          end
+        end
+
+        # Remove a network intercept
+        # @param intercept [String] Intercept ID
+        def remove_intercept(intercept)
+          raise BrowserDisconnectedError, @reason if disconnected?
+          @session.async_send_command('network.removeIntercept', { intercept: intercept })
+        end
+
+        protected
+
+        def perform_dispose
+          @reason ||= 'Browser was disconnected, probably because the session ended'
+          emit(:closed, { reason: @reason }) if @closed
+          emit(:disconnected, { reason: @reason })
+          @disposables.dispose
+          super
+        end
+
+        private
+
+        def initialize_browser
+          Async do
+            # Listen for session end
+            @session.on(:ended) do |data|
+              dispose_browser(data[:reason])
+            end
+
+            # Listen for shared worker creation
+            @session.on('script.realmCreated') do |info|
+              next unless info['type'] == 'shared-worker'
+              # Create SharedWorkerRealm when implemented
+              # @shared_workers[info['realm']] = SharedWorkerRealm.from(self, info['realm'], info['origin'])
+            end
+
+            # Sync existing user contexts and browsing contexts
+            sync_user_contexts.wait
+            sync_browsing_contexts.wait
+          end
+        end
+
+        def sync_user_contexts
+          Async do
+            result = @session.async_send_command('browser.getUserContexts', {}).wait
+            user_contexts = result['userContexts']
+
+            user_contexts.each do |context_info|
+              create_user_context_object(context_info['userContext'])
+            end
+          end
+        end
+
+        def sync_browsing_contexts
+          Async do
+            # Get all browsing contexts
+            result = @session.async_send_command('browsingContext.getTree', {}).wait
+            contexts = result['contexts']
+
+            # Track context IDs for detecting created/destroyed contexts during sync
+            context_ids = []
+
+            # Setup temporary listener for context creation during sync
+            temp_listener = @session.on('browsingContext.contextCreated') do |info|
+              context_ids << info['context']
+            end
+
+            # Process all contexts (including nested ones)
+            process_contexts(contexts, context_ids)
+
+            # Remove temporary listener
+            # @session.off('browsingContext.contextCreated', &temp_listener)
+          end
+        end
+
+        def process_contexts(contexts, context_ids)
+          contexts.each do |info|
+            # Emit context created event if not already tracked
+            unless context_ids.include?(info['context'])
+              @session.emit('browsingContext.contextCreated', info)
+            end
+
+            # Process children recursively
+            process_contexts(info['children'], context_ids) if info['children']
+          end
+        end
+
+        def create_user_context_object(id)
+          return @user_contexts[id] if @user_contexts[id]
+
+          user_context = UserContext.create(self, id)
+          @user_contexts[id] = user_context
+
+          # Listen for user context closure
+          user_context.once(:closed) do
+            @user_contexts.delete(id)
+          end
+
+          user_context
+        end
+
+        def dispose_browser(reason, closed: false)
+          @closed = closed
+          @reason = reason
+          dispose
+        end
+      end
+    end
+  end
+end