mimic-browser 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b3b8e7dc2f8a30d2cf5fd0b1c126817088119e09ecf2fa2645560ea5794f84
-  data.tar.gz: 79b4692fee3d5445366cb121e9242a600941424ac2ef012b825d67883963bbcb
+  metadata.gz: 37f584d860c127be652e6c4979dca16dae2dda07263f3a306b9324416071a272
+  data.tar.gz: 2787d67161bac57dd660881b2250ef446dd703117e4591dc2942978132e47a6b
 SHA512:
-  metadata.gz: 7cd0e4de5cc9a2955804d29c4b8eecac61df63bd2ea05692cd832bea3604fc5a27c127aabe169fd0dde0f88d5abaf3bf76552b93874a6adc8fe1a51f98a929f0
-  data.tar.gz: 497504d0545e5c64f13c2f7786f9ab92bd9f1c22b34cdfeb81a6af1d02e8cb3797488e80ab85c8db5de24502f978c40e6534e63910c25a88dda790181e16567b
+  metadata.gz: f9ca3db0cbac5f553e9bdb9d138006cdfe366b17152ca2ace3a577b9d80f743260c3d338aecc87985e9efa45eec5e9ca43d7cb8b67193c52e85d5a505eab0af4
+  data.tar.gz: 1bf217c272574b736d016c0a34487e84734d938b70bc0d0be779b1d571f42f5c4bba390725c48613147a11c9d1b254fd89530e9cec61dd1ae1ae3db827634e71

data/README.md

@@ -3,18 +3,14 @@
 Package `mimic-browser` requires Ruby 3.2+. Ferrum is optional; require
 `mimic_sdk/ferrum` to select it. Core import is inert.
 
-Install from GitHub with the native gem tools. The RubyGems package is not
-published yet:
+Install the SDK from RubyGems and the optional Ferrum client:
 
 ```sh
-git clone https://github.com/mimic-browser/sdk.git
-cd sdk/ruby
-gem build mimic-browser.gemspec
-gem install ./mimic-browser-0.1.0.gem --no-document
+gem install mimic-browser --no-document
 gem install ferrum --version 0.18.0 --no-document
 ```
 
-The bundled v0.2.3 runtime includes the CSS and navigation lifecycle support
+The bundled v0.2.4 runtime includes the CSS and navigation lifecycle support
 required by Ferrum. The first launch downloads and verifies that exact runtime;
 later launches reuse the persistent cache. No executable path is required.
 
@@ -39,8 +35,10 @@ both the browser endpoint and `/devtools/page/*` on the same origin.
 
 `new_context(profile:, media:, resource_policy:, proxy:)` applies Mimic settings
 before returning the native context. A managed profile uses the runtime's
-configure-context bridge. `for_page(page)` creates a page extension session on
-the owned raw connection. Framework session IDs are never copied across sockets.
+configure-context bridge. `for_page(page)` reuses one page capability handle on
+the owned raw connection. Call `handle.close` to detach it early; the native Page
+remains open. Closing the Page or integration invalidates the handle and removes
+its cache entry. Framework session IDs are never copied across sockets.
 
 `media:` also accepts a callable. It receives
 `ContextSetup(browser_context_id:, mimic:)` after native Context creation and
@@ -64,7 +62,10 @@ the adapter's ownership mutex; a failing callback disposes its new Context.
 Media configuration alone keeps ordinary CDP emulation available; only an
 explicit environment profile or proxy selects managed Context configuration.
 
-Typed capabilities use snake_case methods and generated models. `UNSET` omits a
+Runtime and adapter methods expose explicit keyword parameters. Generated models
+also expose named constructors, for example
+`Generated::MediaConfiguration.new(devices: [])`, and documented field/result
+types for editor completion. Typed capabilities use snake_case methods. `UNSET` omits a
 value, while `nil` remains JSON null. Raw wire names retain their exact spelling:
 
 ```ruby
@@ -79,9 +80,9 @@ dispatcher serves generated and experimental calls. `ProtocolError` retains
 after dispatch does not imply rollback and does not cause automatic retries.
 
 `RuntimeManager.new(runtime_version:, lock_file:, executable_path:, runtime_dir:,
-allow_download:, archive_path:, startup_timeout:, cancelled:)` follows the shared
+allow_download:, archive_path:, startup_timeout:, lock_timeout:, cancelled:)` follows the shared
 runtime contract. It provides `resolve_lock`, `install`, `launch`, `list`,
-`verify` and explicit `prune`. The packaged pin is v0.2.3. Exact archives and
+`verify` and explicit `prune`. The packaged pin is v0.2.4. Exact archives and
 executables are hash-verified; all languages reuse the same OS cache and leases.
 Use `mimic-sdk install --offline --archive /path/to/official.tar.gz`, `list`,
 `verify`, or `lock` for deliberate cache operations.

data/lib/mimic_sdk/ferrum.rb

@@ -8,15 +8,30 @@ end
 
 module MimicSDK
   module Ferrum
+    # Identity and typed capabilities for the context being configured.
+    # @!attribute [rw] browser_context_id
+    #   @return [String]
+    # @!attribute [rw] mimic
+    #   @return [MimicSDK::Client]
     ContextSetup = Struct.new(:browser_context_id, :mimic, keyword_init: true)
 
     class Session
-      attr_reader :browser, :mimic, :runtime
+      # @return [::Ferrum::Browser]
+      attr_reader :browser
+      # @return [MimicSDK::Client]
+      attr_reader :mimic
+      # @return [MimicSDK::RuntimeProcess, nil] nil when attached to an external runtime
+      attr_reader :runtime
 
+      # @param endpoint [String] HTTP or browser WebSocket endpoint
+      # @param runtime [MimicSDK::RuntimeProcess, nil]
+      # @param timeout [Numeric] native client timeout in seconds
       def initialize(endpoint, runtime: nil, timeout: 30)
         @runtime = runtime
         @contexts = []
+        @page_clients = {}
         @mutex = Mutex.new
+        @close_changed = ConditionVariable.new
         @transport = runtime ? runtime.transport : Transport.new(endpoint, timeout: timeout)
         @mimic = Client.new(@transport)
         version = @mimic.get_version
@@ -27,6 +42,23 @@ module MimicSDK
         @browser = ::Ferrum::Browser.new(
           ws_url: @transport.url, timeout: timeout, process_timeout: timeout, flatten: false
         )
+        events, @unsubscribe = @transport.subscribe
+        @attachment_events = Thread.new do
+          while (event = events.pop)
+            next unless event['method'] == 'Target.detachedFromTarget'
+            @mutex.synchronize do
+              @page_clients.delete_if do |_target, client|
+                detached = client.session_id == event.dig('params', 'sessionId')
+                detached && client.invalidate
+              end
+            end
+          end
+        ensure
+          @mutex.synchronize do
+            # A pending explicit detach remains owned until its reply/failure.
+            @page_clients.delete_if { |_target, client| client.invalidate }
+          end
+        end
       rescue StandardError
         close
         raise
@@ -34,6 +66,12 @@ module MimicSDK
 
       # Returns Ferrum::Context, not an SDK automation wrapper. All configuration
       # is complete before a user Page can be created through the returned object.
+      # @param profile [String, MimicSDK::Generated::GenerateProfileSelection, Hash]
+      # @param media [MimicSDK::Generated::MediaConfiguration, Hash, Proc, nil]
+      #   A Proc receives ContextSetup and returns MediaConfiguration or its wire Hash.
+      # @param resource_policy [MimicSDK::Generated::ResourcePolicy, Hash, nil]
+      # @param proxy [MimicSDK::Generated::Proxy, Hash, nil]
+      # @return [::Ferrum::Context]
       def new_context(profile: UNSET, media: nil, resource_policy: nil, proxy: nil)
         context = @mutex.synchronize do
           raise RuntimeError, 'Integration session closed' if @closed
@@ -74,34 +112,102 @@ module MimicSDK
         end
       end
 
+      # @param page [::Ferrum::Page]
+      # @return [MimicSDK::PageClient] cached until detached; close releases only this attachment
       def for_page(page)
         raise ArgumentError, 'Expected an actual Ferrum::Page' unless page.is_a?(::Ferrum::Page)
-        session = @transport.call_raw('Target.attachToTarget', { 'targetId' => page.target_id, 'flatten' => true })
-        Client.new(@transport, session_id: session.fetch('sessionId'))
+        loop do
+          client = @mutex.synchronize do
+            raise RuntimeError, 'Integration session closed' if @closed
+            @page_clients[page.target_id] ||= begin
+              session = @transport.call_raw('Target.attachToTarget', { 'targetId' => page.target_id, 'flatten' => true })
+              PageClient.new(@transport, session_id: session.fetch('sessionId'), detach: method(:detach_page_client))
+            end
+          end
+          return client unless client.closed?
+          # Never replace a closing handle before its cleanup finishes. Waiting
+          # outside the Session mutex allows detach to release its ownership.
+          client.close
+        end
+      end
+
+      def detach_page_client(client)
+        @transport.call_raw('Target.detachFromTarget', { 'sessionId' => client.session_id })
+      rescue ProtocolError => error
+        # The target can close between local invalidation and the detach command.
+        raise unless error.code == -32000 && error.message == 'No session with given id'
+      ensure
+        @mutex.synchronize { @page_clients.delete_if { |_target, owned| owned.equal?(client) } }
       end
+      private :detach_page_client
 
       def close
         return unless @mutex
-        @mutex.synchronize do
-          return if @closed
+        contexts, clients = @mutex.synchronize do
+          @close_changed.wait(@mutex) while @closing
+          if @closed
+            raise @close_error if @close_error
+            return
+          end
           @closed = true
-          begin
-            @contexts.each(&:dispose)
-          ensure
-            begin
-              @browser&.quit # Remote Ferrum owns no process; quit only disconnects.
-            ensure
-              @runtime ? @runtime.close : @transport&.close
-            end
+          @closing = true
+          owned = [@contexts, @page_clients.values]
+          @contexts = []
+          @page_clients = {}
+          owned
+        end
+        failure = nil
+        cleanup = lambda do |&operation|
+          operation.call
+        rescue StandardError => error
+          failure ||= error
+        end
+        begin
+          clients.each { |client| cleanup.call { client.close } }
+          contexts.each { |context| cleanup.call { context.dispose } }
+          cleanup.call { @browser&.quit } # A remote Ferrum browser owns no process.
+          cleanup.call { @runtime ? @runtime.close : @transport&.close }
+        ensure
+          clients.each(&:invalidate)
+          cleanup.call { @unsubscribe&.call }
+          cleanup.call { @attachment_events&.join unless @attachment_events == Thread.current }
+          @mutex.synchronize do
+            @close_error = failure
+            @closing = false
+            @close_changed.broadcast
           end
         end
+        raise failure if failure
         nil
       end
     end
 
-    def self.launch(**options)
-      process = RuntimeManager.new(**options).launch
-      session = Session.new(process.endpoint, runtime: process)
+    # @param runtime_version [String, nil]
+    # @param lock_file [String, nil]
+    # @param executable_path [String, nil]
+    # @param runtime_dir [String, nil]
+    # @param archive_path [String, nil]
+    # @param allow_download [Boolean] omitted to use the environment default
+    # @param startup_timeout [Numeric] seconds
+    # @param lock_timeout [Numeric] seconds
+    # @param cancelled [Proc, nil] returns true to cancel
+    # @param timeout [Numeric] native client timeout in seconds
+    # @yield [session] closes the session after the block
+    # @yieldparam session [MimicSDK::Ferrum::Session]
+    # @return [MimicSDK::Ferrum::Session] when called without a block;
+    #   the block form returns the block's result instead
+    def self.launch(runtime_version: nil, lock_file: nil, executable_path: nil,
+                    runtime_dir: nil, archive_path: nil, allow_download: UNSET,
+                    startup_timeout: 30, lock_timeout: 120, cancelled: nil,
+                    timeout: 30)
+      process = RuntimeManager.new(
+        runtime_version: runtime_version, lock_file: lock_file,
+        executable_path: executable_path, runtime_dir: runtime_dir,
+        archive_path: archive_path, allow_download: allow_download,
+        startup_timeout: startup_timeout, lock_timeout: lock_timeout,
+        cancelled: cancelled
+      ).launch
+      session = Session.new(process.endpoint, runtime: process, timeout: timeout)
       return session unless block_given?
       begin
         yield session
@@ -113,8 +219,14 @@ module MimicSDK
       raise
     end
 
-    def self.connect(endpoint, **options)
-      session = Session.new(endpoint, **options)
+    # @param endpoint [String] HTTP or browser WebSocket endpoint
+    # @param timeout [Numeric] native client timeout in seconds
+    # @yield [session] closes the session after the block
+    # @yieldparam session [MimicSDK::Ferrum::Session]
+    # @return [MimicSDK::Ferrum::Session] when called without a block;
+    #   the block form returns the block's result instead
+    def self.connect(endpoint, timeout: 30)
+      session = Session.new(endpoint, timeout: timeout)
       return session unless block_given?
       begin
         yield session