mimic-browser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0b3b8e7dc2f8a30d2cf5fd0b1c126817088119e09ecf2fa2645560ea5794f84
+  data.tar.gz: 79b4692fee3d5445366cb121e9242a600941424ac2ef012b825d67883963bbcb
+SHA512:
+  metadata.gz: 7cd0e4de5cc9a2955804d29c4b8eecac61df63bd2ea05692cd832bea3604fc5a27c127aabe169fd0dde0f88d5abaf3bf76552b93874a6adc8fe1a51f98a929f0
+  data.tar.gz: 497504d0545e5c64f13c2f7786f9ab92bd9f1c22b34cdfeb81a6af1d02e8cb3797488e80ab85c8db5de24502f978c40e6534e63910c25a88dda790181e16567b

data/LICENSE

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: moreveal
+
+Source Code: https://github.com/moreveal/mimic
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

data/README.md

@@ -0,0 +1,96 @@
+# Mimic for Ruby
+
+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:
+
+```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 ferrum --version 0.18.0 --no-document
+```
+
+The bundled v0.2.3 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.
+
+```ruby
+require 'mimic_sdk/ferrum'
+
+MimicSDK::Ferrum.launch do |session|
+  context = session.new_context
+  page = context.create_page
+  page.go_to('https://example.com')
+  puts page.title
+  puts session.mimic.get_version.version
+end
+```
+
+The returned browser, context and page are actual Ferrum objects. `connect`
+attaches without installing or starting a runtime; closing it preserves the
+external process and other clients. `launch` owns startup and bounded cleanup.
+All launches are headless and bind an OS-assigned loopback port.
+Ferrum uses a dedicated WebSocket for each Page. A reverse proxy must forward
+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.
+
+`media:` also accepts a callable. It receives
+`ContextSetup(browser_context_id:, mimic:)` after native Context creation and
+before configuration or any user Page. Discover sources in that Context:
+
+```ruby
+context = session.new_context(media: lambda do |setup|
+  sources = setup.mimic.get_media_sources({ 'browserContextId' => setup.browser_context_id }).sources
+  microphone = sources.find { |source| source.kind == 'audioinput' }
+  raise 'No microphone source available' unless microphone
+  { 'devices' => [{
+    'key' => 'voice', 'kind' => 'audioinput', 'label' => 'Studio Microphone',
+    'source' => { 'sourceId' => microphone.source_id }
+  }] }
+end)
+```
+
+Private source IDs select capture backends independently of public labels, keys,
+groups and camera modes. Discovery does not open capture. Callbacks run outside
+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
+value, while `nil` remains JSON null. Raw wire names retain their exact spelling:
+
+```ruby
+session.mimic.experimental.newContributorCommand({ 'enabled' => true })
+session.mimic.experimental.call('newContributorCommand', { 'enabled' => true })
+```
+
+Inspection is inert and explicit `call` handles reserved names. The same
+dispatcher serves generated and experimental calls. `ProtocolError` retains
+`code`, `message`, and `data`; missing error data differs from explicit null.
+`timeout:` and `cancelled: -> { ... }` are supported by raw calls. Cancellation
+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
+runtime contract. It provides `resolve_lock`, `install`, `launch`, `list`,
+`verify` and explicit `prune`. The packaged pin is v0.2.3. 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.
+
+Run `test/sdk_test.rb`, `test/transport_test.rb`, and `test/ferrum_test.rb` inside
+Linux/WSL. Real fixture tests cover reverse-order concurrent replies, event order,
+omission/null, structured errors, cancellation, disconnect, archive integrity,
+native automation and owned/attached cleanup. Exact runtime/framework evidence
+belongs in the repository's qualification receipts.
+`test/media_test.rb` requires `MIMIC_MEDIA_FIXTURE` pointing to the explicit
+synthetic-provider fixture. It verifies native capture and public identity
+without opening physical devices.

data/bin/mimic-sdk

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require 'mimic_sdk'
+
+command = ARGV.shift
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = 'mimic-sdk install|list|verify|prune|lock [options]'
+  opts.on('--version VERSION') { |value| options[:runtime_version] = value }
+  opts.on('--lock FILE') { |value| options[:lock_file] = value }
+  opts.on('--runtime-dir DIR') { |value| options[:runtime_dir] = value }
+  opts.on('--archive FILE') { |value| options[:archive_path] = value }
+  opts.on('--offline') { options[:allow_download] = false }
+  opts.on('--directory DIR') { |value| options[:directory] = value }
+end
+parser.parse!
+manager = MimicSDK::RuntimeManager.new(**options)
+result = case command
+         when 'install' then manager.install
+         when 'list' then manager.list
+         when 'verify', 'prune'
+           abort('--directory is required') unless options[:directory]
+           installation = manager.verify(options[:directory])
+           manager.prune(installation) if command == 'prune'
+           installation
+         when 'lock' then manager.resolve_lock
+         else abort(parser.to_s)
+         end
+puts JSON.pretty_generate(result)

data/lib/mimic_sdk/ferrum.rb

@@ -0,0 +1,126 @@
+require 'mimic_sdk'
+
+begin
+  require 'ferrum'
+rescue LoadError => error
+  raise LoadError, "Install the selected adapter dependency with `gem install ferrum`: #{error.message}"
+end
+
+module MimicSDK
+  module Ferrum
+    ContextSetup = Struct.new(:browser_context_id, :mimic, keyword_init: true)
+
+    class Session
+      attr_reader :browser, :mimic, :runtime
+
+      def initialize(endpoint, runtime: nil, timeout: 30)
+        @runtime = runtime
+        @contexts = []
+        @mutex = Mutex.new
+        @transport = runtime ? runtime.transport : Transport.new(endpoint, timeout: timeout)
+        @mimic = Client.new(@transport)
+        version = @mimic.get_version
+        raise RuntimeError, 'Endpoint is not Mimic' if version.version.to_s.empty? || version.chrome_version.to_s.empty?
+        # Ferrum resolves target creation before its flattened session may be
+        # attached. A dedicated target socket binds each Page immediately and
+        # avoids caching a SessionClient with a missing session ID.
+        @browser = ::Ferrum::Browser.new(
+          ws_url: @transport.url, timeout: timeout, process_timeout: timeout, flatten: false
+        )
+      rescue StandardError
+        close
+        raise
+      end
+
+      # Returns Ferrum::Context, not an SDK automation wrapper. All configuration
+      # is complete before a user Page can be created through the returned object.
+      def new_context(profile: UNSET, media: nil, resource_policy: nil, proxy: nil)
+        context = @mutex.synchronize do
+          raise RuntimeError, 'Integration session closed' if @closed
+          created = browser.contexts.create
+          @contexts << created
+          created
+        end
+        begin
+          factory = media.respond_to?(:call)
+          # User callbacks run without the ownership mutex and may await their
+          # own work, create another Context or close this Session.
+          media = media.call(ContextSetup.new(browser_context_id: context.id, mimic: mimic)) if factory
+          if factory && !media.is_a?(Hash) && !media.is_a?(Generated::MediaConfiguration)
+            raise ArgumentError, 'Media factory must return a media configuration'
+          end
+          @mutex.synchronize { raise RuntimeError, 'Integration session closed' if @closed }
+          if !profile.equal?(UNSET) || proxy
+            params = { 'browserContextId' => context.id }
+            params['profile'] = Generated.to_wire(profile) unless profile.equal?(UNSET)
+            params['proxy'] = Generated.to_wire(proxy) if proxy
+            params['media'] = Generated.to_wire(media) if media
+            params['resourcePolicy'] = Generated.to_wire(resource_policy) if resource_policy
+            mimic.configure_context(params)
+          else
+            mimic.set_media_profile(Generated.to_wire(media).merge('browserContextId' => context.id)) if media
+            mimic.update_resource_policy({ 'browserContextId' => context.id, 'policy' => Generated.to_wire(resource_policy) }) if resource_policy
+          end
+          context
+        rescue StandardError
+          begin
+            context.dispose
+            @mutex.synchronize { @contexts.delete(context) }
+          rescue StandardError
+            # Preserve the configuration error; close retains ownership and
+            # retries disposal if cleanup could not be confirmed.
+          end
+          raise
+        end
+      end
+
+      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'))
+      end
+
+      def close
+        return unless @mutex
+        @mutex.synchronize do
+          return if @closed
+          @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
+          end
+        end
+        nil
+      end
+    end
+
+    def self.launch(**options)
+      process = RuntimeManager.new(**options).launch
+      session = Session.new(process.endpoint, runtime: process)
+      return session unless block_given?
+      begin
+        yield session
+      ensure
+        session.close
+      end
+    rescue StandardError
+      process&.close
+      raise
+    end
+
+    def self.connect(endpoint, **options)
+      session = Session.new(endpoint, **options)
+      return session unless block_given?
+      begin
+        yield session
+      ensure
+        session.close
+      end
+    end
+  end
+end