puppeteer-bidi 0.0.2 → 0.0.3.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7242d594b90af9ed2739ef56e234d3d26805cf19d688212e9b0b68ad823a96c2
-  data.tar.gz: 6bca1fe1f82165851376466367cee72ec59f10fabb6b2970a70bcffde5ef42b6
+  metadata.gz: 56fae0e1e155b3fe5bcce854ac7ff615c86af3815b0b9b186bf97fa905421a00
+  data.tar.gz: 3b13efc226d2a7d84da91056679707ff3d0b3a5d511f2211c9cfc4da1c0fef23
 SHA512:
-  metadata.gz: 1c7f73fa6f5351d1e1e12a87388e56c05faa11286bf724e400ec97e19092a81a6e22c6718970c028305717afdaf560ddd16dbfa6f499b5dbc28313b8b55d3347
-  data.tar.gz: ad2cc2f58a6da1d6bff87bde5eab283536f46aa160bbc3ac197c6574f9fd5f35950ca47331c9363feea4a93eaa8af76322f38b123e31d9212206d01e01d2d9d4
+  metadata.gz: abd414f479202d7f642c6f3b4b0ce3db308a18c5116bd4545483b88cf03193cdfb49e41931e596b3cb99c7699ac8f6773ba4ffff7bf160dd8f0a165745f6d0cc
+  data.tar.gz: 62c840fafb7844a586286eb5776b58763e2d7d3547194233e74e75d997aeb239d875fa263b20dbdfe0a326bc2608748c5c4cc479148299096a6b11f43d116cca

data/CLAUDE/reactor_runner.md

@@ -0,0 +1,111 @@
+# ReactorRunner - Using Browser Outside Sync Blocks
+
+## Problem
+
+The socketry/async library requires all async operations to run inside a `Sync do ... end` block. However, some use cases cannot wrap their entire code in a Sync block:
+
+```ruby
+# This pattern doesn't work with plain async:
+browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
+at_exit { browser.close }  # Called outside any Sync block!
+
+Sync do
+  page = browser.new_page
+  page.goto("https://example.com")
+end
+```
+
+The `at_exit` hook runs after the Sync block has finished, so `browser.close` would fail.
+
+## Solution: ReactorRunner
+
+`ReactorRunner` creates a dedicated Async reactor in a background thread and provides a way to execute code within that reactor from any thread.
+
+### How It Works
+
+1. **Background Thread with Reactor**: ReactorRunner spawns a new thread that runs `Sync do ... end` with an `Async::Queue` for receiving jobs
+2. **Proxy Pattern**: Returns a `Proxy` object that wraps the real Browser and forwards all method calls through the ReactorRunner
+3. **Automatic Detection**: `launch_browser_instance` and `connect_to_browser_instance` check `Async::Task.current` to decide whether to use ReactorRunner
+
+### Architecture
+
+```
+Main Thread                     Background Thread (ReactorRunner)
+    │                                    │
+    │  launch_browser_instance()         │
+    │  ─────────────────────────────────>│ Sync do
+    │                                    │   Browser.launch()
+    │  <─────────────────────────────────│   (browser created)
+    │  returns Proxy                     │
+    │                                    │
+    │  proxy.new_page()                  │
+    │  ─────────────────────────────────>│   browser.new_page()
+    │  <─────────────────────────────────│   (returns page)
+    │                                    │
+    │  at_exit { proxy.close }           │
+    │  ─────────────────────────────────>│   browser.close()
+    │                                    │ end
+    │                                    │
+```
+
+### Key Components
+
+#### ReactorRunner
+
+- Creates background thread with `Sync` reactor
+- Uses `Async::Queue` to receive jobs from other threads
+- `sync(&block)` method executes block in reactor and returns result
+- Handles proper cleanup when closed
+
+#### ReactorRunner::Proxy
+
+- Extends `SimpleDelegator` for transparent method forwarding
+- Wraps/unwraps return values (e.g., Page becomes Proxy too)
+- `owns_runner: true` means closing browser also closes the ReactorRunner
+- Handles edge cases like calling `close` after runner is already closed
+
+### Usage Patterns
+
+#### Pattern 1: Block-based (Recommended)
+
+```ruby
+Puppeteer::Bidi.launch do |browser|
+  page = browser.new_page
+  # ... use browser
+end  # automatically closed
+```
+
+#### Pattern 2: Instance with at_exit
+
+```ruby
+browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
+at_exit { browser.close }
+
+Sync do
+  page = browser.new_page
+  page.goto("https://example.com")
+end
+```
+
+#### Pattern 3: Inside existing Async context
+
+```ruby
+Sync do
+  # No ReactorRunner used - browser is returned directly
+  browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
+  page = browser.new_page
+  # ...
+  browser.close
+end
+```
+
+### Implementation Notes
+
+1. **Thread Safety**: `Async::Queue` handles cross-thread communication safely
+2. **Proxyable Check**: Only `Puppeteer::Bidi::*` objects (excluding Core layer) are wrapped in Proxy
+3. **Error Handling**: Errors in reactor are propagated back to calling thread via `Async::Promise`
+4. **Type Annotations**: Return type is `Browser` (Proxy is an internal detail)
+
+### Reference
+
+This pattern is inspired by [async-webdriver](https://github.com/socketry/async-webdriver) by Samuel Williams (author of socketry/async).

data/CLAUDE.md

@@ -186,6 +186,7 @@ See the [CLAUDE/](CLAUDE/) directory for detailed implementation guides:
 
 - **[Two-Layer Architecture](CLAUDE/two_layer_architecture.md)** - Core vs Upper layer, async patterns
 - **[Async Programming](CLAUDE/async_programming.md)** - Fiber-based concurrency with socketry/async
+- **[ReactorRunner](CLAUDE/reactor_runner.md)** - Using browser outside Sync blocks (at_exit, etc.)
 - **[Porting Puppeteer](CLAUDE/porting_puppeteer.md)** - Best practices for implementing features
 - **[Core Layer Gotchas](CLAUDE/core_layer_gotchas.md)** - EventEmitter/Disposable pitfalls, @disposed conflicts
 

data/README.md

@@ -78,9 +78,13 @@ Puppeteer::Bidi.launch(
 ### Connect to an existing browser
 
 ```ruby
-browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
-ws_endpoint = browser.ws_endpoint
-browser.disconnect
+ws_endpoint = nil
+
+Sync do
+  browser = Puppeteer::Bidi.launch_browser_instance(headless: true)
+  ws_endpoint = browser.ws_endpoint
+  browser.disconnect
+end
 
 Puppeteer::Bidi.connect(ws_endpoint) do |session|
   puts "Reconnected to browser"

data/Rakefile

@@ -2,6 +2,13 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
 
 RSpec::Core::RakeTask.new(:spec)
 

data/lib/puppeteer/bidi/browser.rb

@@ -92,7 +92,7 @@ module Puppeteer
         # Start transport connection in background thread with Sync reactor
         # Sync is the preferred way to run async code at the top level
         timeout_ms = ((timeout || 30) * 1000).to_i
-        AsyncUtils.async_timeout(timeout_ms, transport.connect).wait
+        AsyncUtils.async_timeout(timeout_ms) { transport.connect }.wait
 
         connection = Connection.new(transport)
 
@@ -111,7 +111,7 @@ module Puppeteer
         transport = Transport.new(ws_endpoint)
         ws_endpoint = transport.url
         timeout_ms = ((timeout || 30) * 1000).to_i
-        AsyncUtils.async_timeout(timeout_ms, transport.connect).wait
+        AsyncUtils.async_timeout(timeout_ms) { transport.connect }.wait
         connection = Connection.new(transport)
 
         # Verify that this endpoint speaks WebDriver BiDi (and is ready) before creating a new session.

data/lib/puppeteer/bidi/reactor_runner.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "async"
+require "async/promise"
+require "async/queue"
+require "delegate"
+require "thread"
+
+module Puppeteer
+  module Bidi
+    # Runs a dedicated Async reactor in a background thread and proxies calls into it.
+    class ReactorRunner
+      class Proxy < SimpleDelegator
+        # @rbs runner: ReactorRunner -- Reactor runner
+        # @rbs target: untyped -- Target object to proxy
+        # @rbs owns_runner: bool -- Whether to close runner on close/disconnect
+        # @rbs return: void
+        def initialize(runner, target, owns_runner: false)
+          super(target)
+          @runner = runner
+          @owns_runner = owns_runner
+        end
+
+        def method_missing(name, *args, **kwargs, &block)
+          if @owns_runner && @runner.closed? && close_like?(name)
+            return nil
+          end
+
+          begin
+            @runner.sync do
+              args = args.map { |arg| @runner.unwrap(arg) }
+              kwargs = kwargs.transform_values { |value| @runner.unwrap(value) }
+              result = __getobj__.public_send(name, *args, **kwargs, &block)
+              @runner.wrap(result)
+            end
+          ensure
+            @runner.close if @owns_runner && close_like?(name)
+          end
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          __getobj__.respond_to?(name, include_private) || super
+        end
+
+        def class
+          __getobj__.class
+        end
+
+        def is_a?(klass)
+          __getobj__.is_a?(klass)
+        end
+
+        alias kind_of? is_a?
+
+        def instance_of?(klass)
+          __getobj__.instance_of?(klass)
+        end
+
+        def ==(other)
+          __getobj__ == @runner.unwrap(other)
+        end
+
+        def eql?(other)
+          __getobj__.eql?(@runner.unwrap(other))
+        end
+
+        def hash
+          __getobj__.hash
+        end
+
+        private
+
+        def close_like?(name)
+          name == :close || name == :disconnect
+        end
+      end
+
+      # @rbs return: void
+      def initialize
+        @queue = Async::Queue.new
+        @ready = Queue.new
+        @closed = false
+        @thread = Thread.new do
+          Sync do |task|
+            @ready << true
+            @queue.async(parent: task) do |_async_task, job|
+              job.call
+            end
+          ensure
+            @closed = true
+          end
+        end
+
+        @ready.pop
+      end
+
+      # @rbs &block: () -> untyped
+      # @rbs return: untyped
+      def sync(&block)
+        return block.call if runner_thread?
+        raise Error, "ReactorRunner is closed" if closed?
+
+        promise = Async::Promise.new
+        job = lambda do
+          begin
+            promise.resolve(block.call)
+          rescue => e
+            promise.reject(e)
+          end
+        end
+
+        begin
+          @queue << job
+        rescue Async::Queue::ClosedError
+          raise Error, "ReactorRunner is closed"
+        end
+
+        promise.wait
+      end
+
+      # @rbs return: void
+      def close
+        return if closed?
+
+        @closed = true
+        @queue.close
+        @thread.join unless runner_thread?
+      end
+
+      # @rbs return: bool
+      def closed?
+        @closed
+      end
+
+      # @rbs value: untyped
+      # @rbs return: untyped
+      def wrap(value)
+        return value if value.nil? || value.is_a?(Proxy)
+
+        if value.is_a?(Array)
+          return value.map { |item| wrap(item) }
+        end
+
+        return Proxy.new(self, value) if proxyable?(value)
+
+        value
+      end
+
+      # @rbs value: untyped
+      # @rbs return: untyped
+      def unwrap(value)
+        case value
+        when Proxy
+          value.__getobj__
+        when Array
+          value.map { |item| unwrap(item) }
+        when Hash
+          value.transform_values { |item| unwrap(item) }
+        else
+          value
+        end
+      end
+
+      private
+
+      def runner_thread?
+        Thread.current == @thread
+      end
+
+      def proxyable?(value)
+        return false if value.is_a?(Module) || value.is_a?(Class)
+
+        name = value.class.name
+        return false unless name&.start_with?("Puppeteer::Bidi")
+        return false if name.start_with?("Puppeteer::Bidi::Core")
+        return false if value.is_a?(ReactorRunner) || value.is_a?(Proxy)
+
+        true
+      end
+    end
+  end
+end

data/lib/puppeteer/bidi/version.rb

@@ -2,6 +2,6 @@
 
 module Puppeteer
   module Bidi
-    VERSION = "0.0.2"
+    VERSION = "0.0.3.beta1"
   end
 end

data/lib/puppeteer/bidi.rb

@@ -5,6 +5,7 @@ require "puppeteer/bidi/version"
 require "puppeteer/bidi/errors"
 
 require "puppeteer/bidi/async_utils"
+require "puppeteer/bidi/reactor_runner"
 require "puppeteer/bidi/timeout_settings"
 require "puppeteer/bidi/task_manager"
 require "puppeteer/bidi/serializer"
@@ -75,17 +76,39 @@ module Puppeteer
     # @rbs args: Array[String]? -- Additional browser arguments
     # @rbs timeout: Numeric? -- Launch timeout in seconds
     # @rbs accept_insecure_certs: bool -- Accept insecure certificates
-    # @rbs return: Browser -- Browser instance (if no block given)
+    # @rbs return: Browser -- Browser instance
     def self.launch_browser_instance(executable_path: nil, user_data_dir: nil, headless: true, args: nil, timeout: nil,
                                      accept_insecure_certs: false)
-      Browser.launch(
-        executable_path: executable_path,
-        user_data_dir: user_data_dir,
-        headless: headless,
-        args: args,
-        timeout: timeout,
-        accept_insecure_certs: accept_insecure_certs
-      )
+      if async_context?
+        Browser.launch(
+          executable_path: executable_path,
+          user_data_dir: user_data_dir,
+          headless: headless,
+          args: args,
+          timeout: timeout,
+          accept_insecure_certs: accept_insecure_certs
+        )
+      else
+        runner = ReactorRunner.new
+        begin
+          browser = runner.sync do
+            Browser.launch(
+              executable_path: executable_path,
+              user_data_dir: user_data_dir,
+              headless: headless,
+              args: args,
+              timeout: timeout,
+              accept_insecure_certs: accept_insecure_certs
+            )
+          end
+        rescue StandardError
+          runner.close
+          raise
+        end
+        # @type var proxy: Browser
+        proxy = ReactorRunner::Proxy.new(runner, browser, owns_runner: true)
+        proxy
+      end
     end
 
     # Connect to an existing browser instance
@@ -116,7 +139,31 @@ module Puppeteer
     # @rbs accept_insecure_certs: bool -- Accept insecure certificates
     # @rbs return: Browser -- Browser instance
     def self.connect_to_browser_instance(ws_endpoint, timeout: nil, accept_insecure_certs: false)
-      Browser.connect(ws_endpoint, timeout: timeout, accept_insecure_certs: accept_insecure_certs)
+      if async_context?
+        Browser.connect(ws_endpoint, timeout: timeout, accept_insecure_certs: accept_insecure_certs)
+      else
+        runner = ReactorRunner.new
+        begin
+          browser = runner.sync do
+            Browser.connect(ws_endpoint, timeout: timeout, accept_insecure_certs: accept_insecure_certs)
+          end
+        rescue StandardError
+          runner.close
+          raise
+        end
+        # @type var proxy: Browser
+        proxy = ReactorRunner::Proxy.new(runner, browser, owns_runner: true)
+        proxy
+      end
+    end
+
+    # @rbs return: bool -- Whether we're inside an Async task
+    def self.async_context?
+      task = Async::Task.current
+      !task.nil?
+    rescue RuntimeError, NoMethodError
+      false
     end
+    private_class_method :async_context?
   end
 end

data/sig/_external.rbs

@@ -11,12 +11,22 @@ module Async
   def self.call: [T] () { () -> T } -> Task[T]
 
   class Task[T]
+    def self.current: () -> Task[untyped]?
     def wait: () -> T
     def sleep: (Numeric) -> void
     def stop: () -> void
     def with_timeout: [U] (Numeric) { () -> U } -> U
   end
 
+  class Queue[T]
+    class ClosedError < StandardError
+    end
+    def initialize: () -> void
+    def <<: (T) -> void
+    def close: () -> void
+    def async: [U] (?parent: Task[untyped]?) { (Task[untyped], T) -> U } -> void
+  end
+
   class Promise[T]
     def initialize: () -> void
     def wait: () -> T
@@ -126,3 +136,8 @@ class DateTime
   def to_time: () -> Time
 end
 
+# Delegate library
+class SimpleDelegator
+  def __getobj__: () -> untyped
+  def __setobj__: (untyped) -> untyped
+end

data/sig/puppeteer/bidi/reactor_runner.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/puppeteer/bidi/reactor_runner.rb with RBS::Inline
+
+module Puppeteer
+  module Bidi
+    # Runs a dedicated Async reactor in a background thread and proxies calls into it.
+    class ReactorRunner
+      class Proxy < SimpleDelegator
+        # @rbs runner: ReactorRunner -- Reactor runner
+        # @rbs target: untyped -- Target object to proxy
+        # @rbs owns_runner: bool -- Whether to close runner on close/disconnect
+        # @rbs return: void
+        def initialize: (ReactorRunner runner, untyped target, ?owns_runner: bool) -> void
+
+        def method_missing: (untyped name, *untyped args, **untyped kwargs) ?{ (?) -> untyped } -> untyped
+
+        def respond_to_missing?: (untyped name, ?untyped include_private) -> untyped
+
+        def class: () -> untyped
+
+        def is_a?: (untyped klass) -> untyped
+
+        alias kind_of? is_a?
+
+        def instance_of?: (untyped klass) -> untyped
+
+        def ==: (untyped other) -> untyped
+
+        def eql?: (untyped other) -> untyped
+
+        def hash: () -> untyped
+
+        private
+
+        def close_like?: (untyped name) -> untyped
+      end
+
+      # @rbs return: void
+      def initialize: () -> void
+
+      # @rbs &block: () -> untyped
+      # @rbs return: untyped
+      def sync: () { () -> untyped } -> untyped
+
+      # @rbs return: void
+      def close: () -> void
+
+      # @rbs return: bool
+      def closed?: () -> bool
+
+      # @rbs value: untyped
+      # @rbs return: untyped
+      def wrap: (untyped value) -> untyped
+
+      # @rbs value: untyped
+      # @rbs return: untyped
+      def unwrap: (untyped value) -> untyped
+
+      private
+
+      def runner_thread?: () -> untyped
+
+      def proxyable?: (untyped value) -> untyped
+    end
+  end
+end

data/sig/puppeteer/bidi.rbs

@@ -20,7 +20,7 @@ module Puppeteer
     # @rbs args: Array[String]? -- Additional browser arguments
     # @rbs timeout: Numeric? -- Launch timeout in seconds
     # @rbs accept_insecure_certs: bool -- Accept insecure certificates
-    # @rbs return: Browser -- Browser instance (if no block given)
+    # @rbs return: Browser -- Browser instance
     def self.launch_browser_instance: (?executable_path: String?, ?user_data_dir: String?, ?headless: bool, ?args: Array[String]?, ?timeout: Numeric?, ?accept_insecure_certs: bool) -> Browser
 
     # Connect to an existing browser instance
@@ -37,5 +37,8 @@ module Puppeteer
     # @rbs accept_insecure_certs: bool -- Accept insecure certificates
     # @rbs return: Browser -- Browser instance
     def self.connect_to_browser_instance: (String ws_endpoint, ?timeout: Numeric?, ?accept_insecure_certs: bool) -> Browser
+
+    # @rbs return: bool -- Whether we're inside an Async task
+    def self.async_context?: () -> bool
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppeteer-bidi
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3.beta1
 platform: ruby
 authors:
 - YusukeIwaki
@@ -95,6 +95,7 @@ files:
 - CLAUDE/navigation_waiting.md
 - CLAUDE/porting_puppeteer.md
 - CLAUDE/query_handler.md
+- CLAUDE/reactor_runner.md
 - CLAUDE/rspec_pending_vs_skip.md
 - CLAUDE/selector_evaluation.md
 - CLAUDE/test_server_routes.md
@@ -145,6 +146,7 @@ files:
 - lib/puppeteer/bidi/mouse.rb
 - lib/puppeteer/bidi/page.rb
 - lib/puppeteer/bidi/query_handler.rb
+- lib/puppeteer/bidi/reactor_runner.rb
 - lib/puppeteer/bidi/realm.rb
 - lib/puppeteer/bidi/serializer.rb
 - lib/puppeteer/bidi/target.rb
@@ -191,6 +193,7 @@ files:
 - sig/puppeteer/bidi/mouse.rbs
 - sig/puppeteer/bidi/page.rbs
 - sig/puppeteer/bidi/query_handler.rbs
+- sig/puppeteer/bidi/reactor_runner.rbs
 - sig/puppeteer/bidi/realm.rbs
 - sig/puppeteer/bidi/serializer.rbs
 - sig/puppeteer/bidi/target.rbs