rustwright 0.2.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d7e8b181768892ede9b726e55e50f2ef9fdeb37750899dd7945e6048ce6ad69
+  data.tar.gz: 901f1a118117a7afa26981ba613a7fdfb6efd465253b26aa46d75a4827c7463f
+SHA512:
+  metadata.gz: 182385168ed5c9db42334a95ec5bef817dc7be4ce9598bb57b0004b11d1002fc9fae117ca0c3e8e7dc021bce32cefe9543d3acc57fb84624b12a9a67a61e9c1b
+  data.tar.gz: d19f863af9fa37980be323e76aafce95d309453c6fb17305f23d84a0d2bbe4aecad8f7f1ba21368237bb108bd9fa4020a4962a0ca1079dc0c257cf60fe7b04fa

data/README.md

@@ -0,0 +1,106 @@
+# Rustwright Ruby binding
+
+This Phase 0 binding exposes the complete Rustwright alpha API through Ruby's
+stdlib `Fiddle`; it has no native gem dependency and supports Ruby 2.6 or newer.
+JSON is handled by the stdlib `json` package.
+
+## Install (RubyGems)
+
+The platform gems are not published yet. Once available, install the gem with:
+
+```sh
+gem install rustwright
+```
+
+Published gems will include the native C API library and require no separate
+Rust build. Supported gem platforms are `arm64-darwin`, `x86_64-darwin`,
+`aarch64-linux`, and `x86_64-linux`. Windows is not currently shipped because
+the Rust target, Ruby runtime, and RubyGems platform combinations have not yet
+been validated together.
+
+The bundled library lives at
+`lib/rustwright/native/<platform>/librustwright_capi.<dylib|so>`. Runtime
+resolution uses an explicit `library_path` first, then
+`RUSTWRIGHT_CAPI_LIB`, then the bundled native, and finally the source-checkout
+fallback described below.
+
+## Run from source
+
+From the repository root, run the browser smoke test:
+
+```sh
+ruby ruby/smoke.rb --lib target/release/librustwright_capi.dylib
+```
+
+Run the five-case benchmark subset and write its result document:
+
+```sh
+ruby ruby/runner.rb --manifest bindings/cases/smoke.json --lib target/release/librustwright_capi.dylib --out /tmp/ruby-results.json
+```
+
+On Linux, pass the corresponding `.so`. When run from the repository root,
+direct API use defaults to `target/release/librustwright_capi.dylib` (or `.so`)
+and can select another path with `RUSTWRIGHT_CAPI_LIB`; the smoke command uses
+that default when `--lib` is omitted. The runner requires `--lib`, and an
+explicit path always loads that exact library. The runner also supports `--cases
+id1,id2`, preserves manifest order, exits 0 only when all selected cases pass,
+and exits 1 for case failures (invocation/manifest errors use exit 2).
+
+Build a platform gem from an already-built native library with:
+
+```sh
+ruby ruby/package.rb arm64-darwin target/release/librustwright_capi.dylib
+```
+
+The package is written to `ruby/pkg/`; its temporary staged native is removed
+after the build. Replace the platform and extension with one of the supported
+combinations listed above.
+
+Run the dependency-free contract tests with:
+
+```sh
+ruby ruby/test/contract_test.rb
+```
+
+## API
+
+```ruby
+require_relative 'ruby/lib/rustwright'
+
+browser = Rustwright.chromium.launch(headless: true)
+begin
+  page = browser.new_page
+  begin
+    page.goto('data:text/html,<title>Hello</title>')
+    puts page.title
+    bytes = page.screenshot(full_page: true, type: :png)
+  ensure
+    page.close
+  end
+ensure
+  browser.close
+end
+```
+
+`Rustwright.chromium.executable_path` discovers Chromium. Browser methods are
+`new_page`, `close`, and `ws_endpoint`. Page methods are `goto`, `click`,
+`fill`, `title`, `text_content`, `evaluate`, `screenshot`, and `close`.
+Timeouts are milliseconds; omitting one sends IEEE-754 NaN to mean “no explicit
+timeout.” Launch accepts snake_case, camelCase, string, or symbol option keys
+and normalizes them to the core wire shape. Screenshot accepts Ruby snake_case
+or Node camelCase keys and sends the Node screenshot shape.
+
+Native handles are serialized per browser, explicitly closed, and then freed
+exactly once. Returned strings and screenshot buffers are copied into Ruby
+memory before their matching Rustwright free function is called. Call `close`
+in `ensure` blocks as shown; `close` is idempotent.
+
+## Evaluate values
+
+`evaluate` JSON-encodes an explicitly supplied argument (including `nil`) and
+recursively decodes the core CDP wire. Wrapped arrays/objects and repeated or
+cyclic references become Ruby arrays/hashes. Non-finite numbers and BigInts
+become `Float`/`Integer`, dates become `Time`, regexes become `Regexp`, URLs
+become `URI`, and JavaScript errors become `Rustwright::JavaScriptError`.
+JavaScript `undefined`, symbols, and functions have no lossless Ruby value and
+fall back to `nil`.

data/lib/rustwright/manifest.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require_relative '../rustwright'
+
+module Rustwright
+  class ManifestError < Error; end
+
+  module Manifest
+    module_function
+
+    OPERATIONS = %w[
+      goto click fill title textContent evaluate screenshot
+      assertTitle assertText assertEval
+    ].freeze
+
+    CAPTURE_OPERATIONS = %w[title textContent evaluate screenshot].freeze
+
+    def load(path)
+      parsed = JSON.parse(File.read(path, encoding: Encoding::UTF_8))
+      validate!(parsed)
+      parsed
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise ManifestError, "cannot read manifest #{path}: #{e.message}"
+    rescue JSON::ParserError => e
+      raise ManifestError, "invalid manifest JSON: #{e.message}"
+    end
+
+    def validate!(manifest)
+      object!(manifest, '$')
+      keys!(manifest, %w[version cases], %w[version cases], '$')
+      raise ManifestError, '$.version must be 1' unless manifest['version'] == 1
+
+      cases = manifest['cases']
+      array!(cases, '$.cases')
+      raise ManifestError, '$.cases must contain at least one case' if cases.empty?
+
+      ids = {}
+      cases.each_with_index do |benchmark_case, index|
+        path = "$.cases[#{index}]"
+        validate_case!(benchmark_case, path)
+        id = benchmark_case['id']
+        raise ManifestError, "duplicate case id #{id.inspect}" if ids.key?(id)
+
+        ids[id] = true
+      end
+      manifest
+    end
+
+    def validate_case!(benchmark_case, path)
+      object!(benchmark_case, path)
+      keys!(benchmark_case, %w[id description html url repeat steps], %w[id steps], path)
+      non_empty_string!(benchmark_case['id'], "#{path}.id")
+      string!(benchmark_case['description'], "#{path}.description") if benchmark_case.key?('description')
+      string!(benchmark_case['html'], "#{path}.html") if benchmark_case.key?('html')
+      if benchmark_case.key?('url')
+        string!(benchmark_case['url'], "#{path}.url")
+        begin
+          URI.parse(benchmark_case['url'])
+        rescue URI::InvalidURIError => e
+          raise ManifestError, "#{path}.url is not a URI reference: #{e.message}"
+        end
+      end
+      repeat = benchmark_case.fetch('repeat', 1)
+      unless repeat.is_a?(Integer) && repeat.between?(1, 1_000)
+        raise ManifestError, "#{path}.repeat must be an integer between 1 and 1000"
+      end
+
+      steps = benchmark_case['steps']
+      array!(steps, "#{path}.steps")
+      raise ManifestError, "#{path}.steps must contain at least one step" if steps.empty?
+
+      steps.each_with_index do |step, index|
+        step_path = "#{path}.steps[#{index}]"
+        validate_step!(step, step_path, benchmark_case)
+      end
+
+      first_goto = steps.index { |step| step['op'] == 'goto' }
+      if repeat > 1 && first_goto.nil?
+        raise ManifestError, "case #{benchmark_case['id'].inspect} has repeat #{repeat} but no goto step"
+      end
+
+      capture_blocks = if repeat == 1
+                         [steps]
+                       else
+                         [steps[0..first_goto], steps[(first_goto + 1)..-1]]
+                       end
+      capture_blocks.each do |block|
+        validate_unique_captures!(block, benchmark_case['id'])
+      end
+    end
+    private_class_method :validate_case!
+
+    def validate_unique_captures!(steps, case_id)
+      captures = {}
+      steps.each do |step|
+        next unless CAPTURE_OPERATIONS.include?(step['op'])
+
+        capture = step['capture']
+        if captures.key?(capture)
+          raise ManifestError, "duplicate capture #{capture.inspect} in case #{case_id.inspect}"
+        end
+        captures[capture] = true
+      end
+    end
+    private_class_method :validate_unique_captures!
+
+    def validate_step!(step, path, benchmark_case)
+      object!(step, path)
+      non_empty_string!(step['op'], "#{path}.op") if step.key?('op')
+      operation = step['op']
+      raise ManifestError, "#{path}.op is required" if operation.nil?
+      raise ManifestError, "#{path}.op has unknown operation #{operation.inspect}" unless OPERATIONS.include?(operation)
+
+      case operation
+      when 'goto'
+        keys!(step, %w[op url useCaseHtml waitUntil], %w[op], path)
+        sources = [step.key?('url'), step.key?('useCaseHtml')].count(true)
+        raise ManifestError, "#{path} must contain exactly one of url or useCaseHtml" unless sources == 1
+        non_empty_string!(step['url'], "#{path}.url") if step.key?('url')
+        if step.key?('useCaseHtml')
+          raise ManifestError, "#{path}.useCaseHtml must be true" unless step['useCaseHtml'] == true
+          unless benchmark_case.key?('html')
+            raise ManifestError, "#{path}.useCaseHtml requires case html"
+          end
+        end
+        if step.key?('waitUntil')
+          allowed = %w[load domcontentloaded networkidle commit]
+          unless allowed.include?(step['waitUntil'])
+            raise ManifestError, "#{path}.waitUntil must be one of #{allowed.join(', ')}"
+          end
+        end
+      when 'click'
+        keys!(step, %w[op selector], %w[op selector], path)
+        non_empty_string!(step['selector'], "#{path}.selector")
+      when 'fill'
+        keys!(step, %w[op selector value], %w[op selector value], path)
+        non_empty_string!(step['selector'], "#{path}.selector")
+        string!(step['value'], "#{path}.value")
+      when 'title'
+        capture_step!(step, path, %w[op capture])
+      when 'textContent'
+        capture_step!(step, path, %w[op selector capture])
+        non_empty_string!(step['selector'], "#{path}.selector")
+      when 'evaluate'
+        capture_step!(step, path, %w[op expression arg capture], %w[op expression capture])
+        non_empty_string!(step['expression'], "#{path}.expression")
+      when 'screenshot'
+        capture_step!(step, path, %w[op capture])
+      when 'assertTitle'
+        assertion_predicate!(step, path, %w[op equals contains])
+      when 'assertText'
+        assertion_predicate!(step, path, %w[op selector equals contains], %w[op selector])
+        non_empty_string!(step['selector'], "#{path}.selector")
+      when 'assertEval'
+        keys!(step, %w[op expression equals], %w[op expression equals], path)
+        non_empty_string!(step['expression'], "#{path}.expression")
+      end
+    end
+    private_class_method :validate_step!
+
+    def capture_step!(step, path, allowed, required = allowed)
+      keys!(step, allowed, required, path)
+      non_empty_string!(step['capture'], "#{path}.capture")
+    end
+    private_class_method :capture_step!
+
+    def assertion_predicate!(step, path, allowed, required = %w[op])
+      keys!(step, allowed, required, path)
+      predicates = [step.key?('equals'), step.key?('contains')].count(true)
+      raise ManifestError, "#{path} must contain exactly one of equals or contains" unless predicates == 1
+
+      string!(step['equals'], "#{path}.equals") if step.key?('equals')
+      string!(step['contains'], "#{path}.contains") if step.key?('contains')
+    end
+    private_class_method :assertion_predicate!
+
+    def keys!(value, allowed, required, path)
+      unknown = value.keys - allowed
+      missing = required - value.keys
+      raise ManifestError, "#{path} has unknown properties: #{unknown.join(', ')}" unless unknown.empty?
+      raise ManifestError, "#{path} is missing required properties: #{missing.join(', ')}" unless missing.empty?
+    end
+    private_class_method :keys!
+
+    def object!(value, path)
+      raise ManifestError, "#{path} must be an object" unless value.is_a?(Hash)
+    end
+    private_class_method :object!
+
+    def array!(value, path)
+      raise ManifestError, "#{path} must be an array" unless value.is_a?(Array)
+    end
+    private_class_method :array!
+
+    def string!(value, path)
+      raise ManifestError, "#{path} must be a string" unless value.is_a?(String)
+    end
+    private_class_method :string!
+
+    def non_empty_string!(value, path)
+      string!(value, path)
+      raise ManifestError, "#{path} must not be empty" if value.empty?
+    end
+    private_class_method :non_empty_string!
+  end
+end

data/lib/rustwright/native.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+module Rustwright
+  # Thin, ownership-aware wrapper around the complete rustwright C ABI.
+  class Native
+    VOIDP = Fiddle::TYPE_VOIDP
+    INT = Fiddle::TYPE_INT
+    DOUBLE = Fiddle::TYPE_DOUBLE
+    SIZE_T = Fiddle::TYPE_SIZE_T
+    VOID = Fiddle::TYPE_VOID
+
+    SIGNATURES = {
+      rw_last_error: [[], VOIDP],
+      rw_string_free: [[VOIDP], VOID],
+      rw_bytes_free: [[VOIDP, SIZE_T], VOID],
+      rw_chromium_executable_path: [[VOIDP], INT],
+      rw_chromium_launch: [[VOIDP, VOIDP], INT],
+      rw_browser_new_page: [[VOIDP, VOIDP], INT],
+      rw_browser_close: [[VOIDP], INT],
+      rw_browser_ws_endpoint: [[VOIDP], VOIDP],
+      rw_browser_free: [[VOIDP], VOID],
+      rw_page_target_id: [[VOIDP], VOIDP],
+      rw_page_goto: [[VOIDP, VOIDP, VOIDP, DOUBLE, VOIDP, VOIDP], INT],
+      rw_page_click: [[VOIDP, VOIDP, DOUBLE], INT],
+      rw_page_fill: [[VOIDP, VOIDP, VOIDP, DOUBLE], INT],
+      rw_page_title: [[VOIDP, DOUBLE, VOIDP], INT],
+      rw_page_text_content: [[VOIDP, VOIDP, DOUBLE, VOIDP], INT],
+      rw_page_evaluate: [[VOIDP, VOIDP, VOIDP, DOUBLE, VOIDP], INT],
+      rw_page_screenshot: [[VOIDP, VOIDP, VOIDP, VOIDP], INT],
+      rw_page_close: [[VOIDP, DOUBLE, INT], INT],
+      rw_page_free: [[VOIDP], VOID]
+    }.freeze
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = File.expand_path(path)
+      @handle = Fiddle.dlopen(@path)
+      @functions = {}
+      SIGNATURES.each do |name, (arguments, result)|
+        @functions[name] = Fiddle::Function.new(@handle[name.to_s], arguments, result)
+      end
+    rescue Fiddle::DLError => e
+      raise Rustwright::Error, "cannot load Rustwright library #{@path}: #{e.message}"
+    end
+
+    def call(name, *arguments)
+      if arguments.any? { |argument| argument.is_a?(String) && argument.include?("\0") }
+        raise Rustwright::Error, 'strings passed to the C ABI cannot contain NUL'
+      end
+
+      @functions.fetch(name).call(*arguments)
+    end
+
+    # This must be invoked before any other ABI call after a failing status.
+    def check_status!(status, operation)
+      return if status.zero?
+
+      raise Rustwright::Error, last_error_immediately(operation, status)
+    end
+
+    # This must be invoked immediately after a direct pointer return is NULL.
+    def raise_null_error!(operation)
+      raise Rustwright::Error, last_error_immediately(operation, nil)
+    end
+
+    def pointer_slot
+      slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      slot[0, Fiddle::SIZEOF_VOIDP] = [0].pack('J')
+      slot
+    end
+
+    def size_slot
+      slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_SIZE_T)
+      slot[0, Fiddle::SIZEOF_SIZE_T] = [0].pack(size_t_pack)
+      slot
+    end
+
+    def pointer_address(slot)
+      slot[0, Fiddle::SIZEOF_VOIDP].unpack('J').first
+    end
+
+    def size_value(slot)
+      slot[0, Fiddle::SIZEOF_SIZE_T].unpack(size_t_pack).first
+    end
+
+    def null?(pointer)
+      pointer.nil? || pointer.to_i.zero?
+    end
+
+    def copy_owned_string(pointer, nullable: false)
+      if null?(pointer)
+        return nil if nullable
+
+        raise Rustwright::Error, 'Rustwright returned an unexpected NULL string'
+      end
+
+      address = pointer.to_i
+      begin
+        Fiddle::Pointer.new(address).to_s.dup.force_encoding(Encoding::UTF_8)
+      ensure
+        call(:rw_string_free, address)
+      end
+    end
+
+    def copy_owned_bytes(pointer, length)
+      address = pointer.to_i
+      if address.zero?
+        # The ABI transfers even the empty NULL/0 pair; release that exact pair.
+        call(:rw_bytes_free, address, length)
+        return ''.b if length.zero?
+
+        raise Rustwright::Error, "Rustwright returned NULL bytes with length #{length}"
+      end
+
+      begin
+        Fiddle::Pointer.new(address).to_str(length).dup.force_encoding(Encoding::BINARY)
+      ensure
+        call(:rw_bytes_free, address, length)
+      end
+    end
+
+    private
+
+    def last_error_immediately(operation, status)
+      borrowed = call(:rw_last_error)
+      message = if null?(borrowed)
+                  'no native error message was provided'
+                else
+                  Fiddle::Pointer.new(borrowed.to_i).to_s.dup.force_encoding(Encoding::UTF_8)
+                end
+      suffix = status.nil? ? '' : " (status #{status})"
+      "#{operation} failed#{suffix}: #{message}"
+    end
+
+    def size_t_pack
+      case Fiddle::SIZEOF_SIZE_T
+      when 8 then 'Q'
+      when 4 then 'L'
+      else
+        raise Rustwright::Error, "unsupported size_t width: #{Fiddle::SIZEOF_SIZE_T}"
+      end
+    end
+  end
+end

data/lib/rustwright/runner.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../rustwright'
+require_relative 'manifest'
+
+module Rustwright
+  class AssertionError < Error; end
+
+  class Runner
+    def initialize(manifest:, library_path:, case_ids: nil)
+      @manifest = manifest
+      @library_path = library_path
+      @case_ids = case_ids
+    end
+
+    def run
+      cases = selected_cases
+      browser = Rustwright.chromium(library_path: @library_path).launch(headless: true)
+      results = []
+      close_error = nil
+
+      begin
+        cases.each { |benchmark_case| results << run_case(browser, benchmark_case) }
+      ensure
+        begin
+          browser.close
+        rescue StandardError => e
+          close_error = e
+        end
+      end
+
+      if close_error
+        result = results.last
+        if result
+          result['ok'] = false
+          result['error'] ||= "browser close: #{close_error.message}"
+        else
+          raise close_error
+        end
+      end
+
+      { 'lang' => 'ruby', 'results' => results }
+    end
+
+    private
+
+    def selected_cases
+      cases = @manifest['cases']
+      return cases if @case_ids.nil?
+
+      available = cases.each_with_object({}) { |item, ids| ids[item['id']] = true }
+      unknown = @case_ids.reject { |id| available.key?(id) }
+      unless unknown.empty?
+        raise ManifestError, "unknown requested case id(s): #{unknown.join(', ')}"
+      end
+
+      selected = @case_ids.each_with_object({}) { |id, ids| ids[id] = true }
+      cases.select { |item| selected.key?(item['id']) }
+    end
+
+    def run_case(browser, benchmark_case)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      captures = {}
+      error = nil
+      page = nil
+
+      begin
+        page = browser.new_page
+        execute_steps(page, benchmark_case, captures)
+      rescue StandardError => e
+        error = page ? e.message : "page creation: #{e.message}"
+      ensure
+        if page
+          begin
+            page.close
+          rescue StandardError => e
+            error ||= "page close: #{e.message}"
+          end
+        end
+      end
+
+      elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+      result = {
+        'id' => benchmark_case['id'],
+        'ok' => error.nil?,
+        'captures' => captures,
+        'ms' => elapsed_ms.round(3)
+      }
+      result['error'] = error unless error.nil?
+      result
+    end
+
+    def execute_steps(page, benchmark_case, captures)
+      steps = benchmark_case['steps']
+      repeat = benchmark_case.fetch('repeat', 1)
+      return execute_step_block(page, benchmark_case, steps, 0, captures) if repeat == 1
+
+      first_goto = steps.index { |step| step['op'] == 'goto' }
+      unless first_goto
+        raise ManifestError, "case #{benchmark_case['id'].inspect} has repeat #{repeat} but no goto step"
+      end
+
+      execute_step_block(page, benchmark_case, steps[0..first_goto], 0, captures)
+      1.upto(repeat) do |iteration|
+        iteration_captures = {}
+        begin
+          execute_step_block(
+            page,
+            benchmark_case,
+            steps[(first_goto + 1)..-1],
+            first_goto + 1,
+            iteration_captures
+          )
+        rescue StandardError => e
+          captures.merge!(iteration_captures)
+          raise Error, "iteration #{iteration}: #{e.message}"
+        end
+        captures.merge!(iteration_captures)
+      end
+    end
+
+    def execute_step_block(page, benchmark_case, steps, index_offset, captures)
+      steps.each_with_index do |step, index|
+        execute_step(page, benchmark_case, step, captures)
+      rescue StandardError => e
+        raise Error, "step #{index_offset + index + 1}: #{e.message}"
+      end
+    end
+
+    def execute_step(page, benchmark_case, step, captures)
+      case step['op']
+      when 'goto'
+        url = step['useCaseHtml'] ? Rustwright.inline_html_url(benchmark_case['html']) : step['url']
+        page.goto(url, wait_until: step['waitUntil'])
+      when 'click'
+        page.click(step['selector'])
+      when 'fill'
+        page.fill(step['selector'], step['value'])
+      when 'title'
+        insert_capture(captures, step['capture'], page.title)
+      when 'textContent'
+        insert_capture(captures, step['capture'], page.text_content(step['selector']))
+      when 'evaluate'
+        value = if step.key?('arg')
+                  page.evaluate(step['expression'], step['arg'])
+                else
+                  page.evaluate(step['expression'])
+                end
+        insert_capture(captures, step['capture'], value)
+      when 'screenshot'
+        insert_capture(captures, step['capture'], page.screenshot.bytesize)
+      when 'assertTitle'
+        assert_string(page.title, step, 'title')
+      when 'assertText'
+        assert_string(page.text_content(step['selector']), step, "textContent for #{step['selector'].inspect}")
+      when 'assertEval'
+        actual = page.evaluate(step['expression'])
+        return if actual == step['equals']
+
+        raise AssertionError, "expected evaluation #{step['equals'].inspect}, got #{actual.inspect}"
+      else
+        # Validation makes this unreachable, but retain a defensive boundary.
+        raise ManifestError, "unknown operation #{step['op'].inspect}"
+      end
+    end
+
+    def insert_capture(captures, name, value)
+      raise ManifestError, "duplicate capture name #{name.inspect}" if captures.key?(name)
+
+      captures[name] = value
+    end
+
+    def assert_string(actual, step, label)
+      raise AssertionError, "expected #{label} to be a string, got null" if actual.nil?
+
+      if step.key?('equals')
+        return if actual == step['equals']
+
+        raise AssertionError, "expected #{label} #{step['equals'].inspect}, got #{actual.inspect}"
+      end
+
+      return if actual.include?(step['contains'])
+
+      raise AssertionError, "expected #{label} to contain #{step['contains'].inspect}, got #{actual.inspect}"
+    end
+  end
+end

data/lib/rustwright/wire.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'uri'
+
+module Rustwright
+  class JavaScriptError < StandardError
+    attr_reader :javascript_name, :javascript_stack
+
+    def initialize(value)
+      @javascript_name = value['name'] || 'Error'
+      @javascript_stack = value['stack'] || ''
+      super(value['message'] || '')
+    end
+  end
+
+  module Wire
+    module_function
+
+    MARKER = '__rustwright_cdp_unserializable_value__'
+
+    def decode(value)
+      decode_value(value, {})
+    end
+
+    def decode_value(value, references)
+      case value
+      when Array
+        value.map { |item| decode_value(item, references) }
+      when Hash
+        decode_hash(value, references)
+      else
+        value
+      end
+    end
+    private_class_method :decode_value
+
+    def decode_hash(value, references)
+      if value.key?('__rustwright_cdp_array__')
+        target = []
+        references[value['__rustwright_cdp_array__']] = target
+        target.concat(Array(value['items']).map { |item| decode_value(item, references) })
+        return target
+      end
+
+      if value.key?('__rustwright_cdp_object__')
+        target = {}
+        references[value['__rustwright_cdp_object__']] = target
+        Hash(value['entries']).each do |key, item|
+          target[key] = decode_value(item, references)
+        end
+        return target
+      end
+
+      if value.key?('__rustwright_cdp_ref__')
+        return references[value['__rustwright_cdp_ref__']]
+      end
+
+      return nil if value.key?('__rustwright_cdp_undefined__')
+      return nil if value.key?('__rustwright_cdp_symbol__')
+      return nil if value.key?('__rustwright_cdp_function__')
+
+      if value.key?(MARKER)
+        return decode_unserializable(value[MARKER])
+      end
+
+      if value.key?('__rustwright_cdp_date__')
+        return Time.iso8601(value['__rustwright_cdp_date__'])
+      end
+
+      if value.key?('__rustwright_cdp_regexp__')
+        regexp = value['__rustwright_cdp_regexp__']
+        return Regexp.new(regexp['p'], regexp_options(regexp['f'].to_s))
+      end
+
+      if value.key?('__rustwright_cdp_url__')
+        return URI.parse(value['__rustwright_cdp_url__'])
+      end
+
+      if value.key?('__rustwright_cdp_error__')
+        return JavaScriptError.new(value['__rustwright_cdp_error__'])
+      end
+
+      value.each_with_object({}) do |(key, item), decoded|
+        decoded[key] = decode_value(item, references)
+      end
+    end
+    private_class_method :decode_hash
+
+    def decode_unserializable(value)
+      case value
+      when 'NaN' then Float::NAN
+      when 'Infinity' then Float::INFINITY
+      when '-Infinity' then -Float::INFINITY
+      when '-0' then -0.0
+      else
+        value.is_a?(String) && value.match?(/\A-?\d+n\z/) ? value[0...-1].to_i : value
+      end
+    end
+    private_class_method :decode_unserializable
+
+    def regexp_options(flags)
+      options = 0
+      options |= Regexp::IGNORECASE if flags.include?('i')
+      # JavaScript's dotAll flag is Ruby's multiline option.
+      options |= Regexp::MULTILINE if flags.include?('s')
+      options
+    end
+    private_class_method :regexp_options
+  end
+end

data/lib/rustwright.rb

@@ -0,0 +1,479 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'monitor'
+require 'rbconfig'
+
+module Rustwright
+  VERSION = '0.2.0'
+  UNSET = Object.new.freeze
+
+  class Error < StandardError; end
+  class ClosedError < Error; end
+
+  module Normalize
+    module_function
+
+    LAUNCH_KEYS = {
+      'headless' => 'headless',
+      'executablePath' => 'executable_path',
+      'executable_path' => 'executable_path',
+      'channel' => 'channel',
+      'args' => 'args',
+      'ignoreAllDefaultArgs' => 'ignore_all_default_args',
+      'ignore_all_default_args' => 'ignore_all_default_args',
+      'ignoreDefaultArgs' => 'ignore_default_args',
+      'ignore_default_args' => 'ignore_default_args',
+      'timeout' => 'timeout',
+      'userDataDir' => 'user_data_dir',
+      'user_data_dir' => 'user_data_dir',
+      'env' => 'env',
+      'chromiumSandbox' => 'chromium_sandbox',
+      'chromium_sandbox' => 'chromium_sandbox',
+      'proxy' => 'proxy'
+    }.freeze
+
+    SCREENSHOT_KEYS = {
+      'path' => 'path',
+      'fullPage' => 'fullPage',
+      'full_page' => 'fullPage',
+      'clip' => 'clip',
+      'timeout' => 'timeout',
+      'type' => 'type',
+      'quality' => 'quality',
+      'omitBackground' => 'omitBackground',
+      'omit_background' => 'omitBackground'
+    }.freeze
+
+    def launch(options)
+      normalize_known_hash(options || {}, LAUNCH_KEYS, 'launch options')
+    end
+
+    def screenshot(options)
+      return nil if options.nil? || options.empty?
+
+      normalize_known_hash(options, SCREENSHOT_KEYS, 'screenshot options')
+    end
+
+    def option_hash(options, keywords, allowed, context)
+      base = options.nil? ? {} : options
+      raise ArgumentError, "#{context} must be a Hash" unless base.is_a?(Hash)
+
+      merged = base.merge(keywords)
+      normalize_known_hash(merged, allowed, context)
+    end
+
+    def normalize_known_hash(value, mapping, context)
+      raise ArgumentError, "#{context} must be a Hash" unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, item), normalized|
+        source_key = key.to_s
+        target_key = mapping[source_key]
+        raise ArgumentError, "unknown #{context} key #{key.inspect}" unless target_key
+        raise ArgumentError, "duplicate #{context} key #{target_key.inspect}" if normalized.key?(target_key)
+
+        normalized[target_key] = json_value(item)
+      end
+    end
+
+    def json_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), result| result[key.to_s] = json_value(item) }
+      when Array
+        value.map { |item| json_value(item) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+  end
+end
+
+require_relative 'rustwright/native'
+require_relative 'rustwright/wire'
+
+module Rustwright
+  class << self
+    def default_library_path
+      # Installed platform gems carry one matching native. Source checkouts keep
+      # the historical repository-relative target/release fallback.
+      bundled_library_path || source_library_path
+    end
+
+    def chromium(library_path: nil)
+      # An explicit argument or environment override remains an exact pin.
+      path = library_path || ENV['RUSTWRIGHT_CAPI_LIB'] || default_library_path
+      Chromium.new(native_for(path))
+    end
+
+    def bundled_library_path
+      platform, extension = bundled_platform
+      return nil unless platform
+
+      path = File.join(__dir__, 'rustwright', 'native', platform, "librustwright_capi.#{extension}")
+      File.file?(path) ? path : nil
+    end
+
+    def inline_html_url(html)
+      raise ArgumentError, 'html must be a String' unless html.is_a?(String)
+
+      encoded = html.encode(Encoding::UTF_8).bytes.map do |byte|
+        if (byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122) ||
+           (byte >= 48 && byte <= 57) || [45, 46, 95, 126].include?(byte)
+          byte.chr
+        else
+          format('%%%02X', byte)
+        end
+      end.join
+      "data:text/html;charset=utf-8,#{encoded}"
+    end
+
+    private
+
+    def source_library_path
+      extension = RbConfig::CONFIG['host_os'].match?(/darwin/) ? 'dylib' : 'so'
+      File.join('target', 'release', "librustwright_capi.#{extension}")
+    end
+
+    def bundled_platform
+      cpu = RbConfig::CONFIG['host_cpu']
+      os = RbConfig::CONFIG['host_os']
+
+      if os.match?(/darwin/)
+        return ['arm64-darwin', 'dylib'] if cpu.match?(/arm64|aarch64/)
+        return ['x86_64-darwin', 'dylib'] if cpu.match?(/x86_64|amd64/)
+      elsif os.match?(/linux/)
+        return ['aarch64-linux', 'so'] if cpu.match?(/arm64|aarch64/)
+        return ['x86_64-linux', 'so'] if cpu.match?(/x86_64|amd64/)
+      end
+
+      nil
+    end
+
+    def native_for(path)
+      expanded = File.expand_path(path)
+      native_mutex.synchronize do
+        native_instances[expanded] ||= Native.new(expanded)
+      end
+    end
+
+    def native_instances
+      @native_instances ||= {}
+    end
+
+    def native_mutex
+      @native_mutex ||= Mutex.new
+    end
+  end
+
+  class Chromium
+    def initialize(native)
+      @native = native
+    end
+
+    def executable_path
+      out = @native.pointer_slot
+      status = @native.call(:rw_chromium_executable_path, out)
+      @native.check_status!(status, 'rw_chromium_executable_path')
+      @native.copy_owned_string(@native.pointer_address(out), nullable: true)
+    end
+
+    def launch(options = nil, **keywords)
+      base = options || {}
+      raise ArgumentError, 'launch options must be a Hash' unless base.is_a?(Hash)
+
+      merged = base.merge(keywords)
+      normalized = Normalize.launch(merged)
+      out = @native.pointer_slot
+      status = @native.call(:rw_chromium_launch, JSON.generate(normalized), out)
+      @native.check_status!(status, 'rw_chromium_launch')
+      handle = @native.pointer_address(out)
+      raise Error, 'rw_chromium_launch returned an unexpected NULL browser' if handle.zero?
+
+      Browser.new(@native, handle)
+    end
+  end
+
+  class Browser
+    def initialize(native, handle)
+      @native = native
+      @handle = handle
+      @monitor = Monitor.new
+      @pages = []
+    end
+
+    def new_page
+      synchronize do
+        ensure_open!
+        out = @native.pointer_slot
+        status = @native.call(:rw_browser_new_page, @handle, out)
+        @native.check_status!(status, 'rw_browser_new_page')
+        page_handle = @native.pointer_address(out)
+        raise Error, 'rw_browser_new_page returned an unexpected NULL page' if page_handle.zero?
+
+        Page.new(@native, self, page_handle).tap { |page| @pages << page }
+      end
+    end
+
+    def ws_endpoint
+      synchronize do
+        ensure_open!
+        pointer = @native.call(:rw_browser_ws_endpoint, @handle)
+        @native.raise_null_error!('rw_browser_ws_endpoint') if @native.null?(pointer)
+        @native.copy_owned_string(pointer)
+      end
+    end
+
+    def close
+      synchronize do
+        return nil if @handle.nil?
+
+        errors = []
+        @pages.dup.each do |page|
+          begin
+            page.close
+          rescue StandardError => e
+            errors << e
+          end
+        end
+
+        handle = @handle
+        begin
+          status = @native.call(:rw_browser_close, handle)
+          @native.check_status!(status, 'rw_browser_close')
+        rescue StandardError => e
+          errors << e
+        ensure
+          @native.call(:rw_browser_free, handle)
+          @handle = nil
+          @pages.clear
+        end
+
+        raise errors.first unless errors.empty?
+
+        nil
+      end
+    end
+
+    def closed?
+      synchronize { @handle.nil? }
+    end
+
+    # Internal synchronization shared by every page belonging to this browser.
+    def synchronize(&block)
+      @monitor.synchronize(&block)
+    end
+
+    def remove_page(page)
+      synchronize { @pages.delete(page) }
+    end
+
+    private
+
+    def ensure_open!
+      raise ClosedError, 'browser is closed' if @handle.nil?
+    end
+  end
+
+  class Page
+    SIMPLE_TIMEOUT_KEYS = { 'timeout' => 'timeout' }.freeze
+    GOTO_KEYS = {
+      'waitUntil' => 'wait_until',
+      'wait_until' => 'wait_until',
+      'timeout' => 'timeout',
+      'referer' => 'referer'
+    }.freeze
+    CLOSE_KEYS = {
+      'timeout' => 'timeout',
+      'runBeforeUnload' => 'run_before_unload',
+      'run_before_unload' => 'run_before_unload'
+    }.freeze
+
+    def initialize(native, browser, handle)
+      @native = native
+      @browser = browser
+      @handle = handle
+      @monitor = Monitor.new
+    end
+
+    def target_id
+      native_call do
+        pointer = @native.call(:rw_page_target_id, @handle)
+        @native.raise_null_error!('rw_page_target_id') if @native.null?(pointer)
+        @native.copy_owned_string(pointer)
+      end
+    end
+
+    def goto(url, options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, GOTO_KEYS, 'goto options')
+      url = input_string(url, 'url')
+      wait_until = nullable_input_string(opts['wait_until'], 'wait_until')
+      referer = nullable_input_string(opts['referer'], 'referer')
+
+      native_call do
+        out = @native.pointer_slot
+        status = @native.call(
+          :rw_page_goto,
+          @handle,
+          url,
+          wait_until || 0,
+          timeout(opts['timeout']),
+          referer || 0,
+          out
+        )
+        @native.check_status!(status, 'rw_page_goto')
+        json = @native.copy_owned_string(@native.pointer_address(out), nullable: true)
+        json.nil? ? nil : JSON.parse(json)
+      end
+    end
+
+    def click(selector, options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, SIMPLE_TIMEOUT_KEYS, 'click options')
+      selector = input_string(selector, 'selector')
+      native_call do
+        status = @native.call(:rw_page_click, @handle, selector, timeout(opts['timeout']))
+        @native.check_status!(status, 'rw_page_click')
+        nil
+      end
+    end
+
+    def fill(selector, value, options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, SIMPLE_TIMEOUT_KEYS, 'fill options')
+      selector = input_string(selector, 'selector')
+      value = input_string(value, 'value')
+      native_call do
+        status = @native.call(:rw_page_fill, @handle, selector, value, timeout(opts['timeout']))
+        @native.check_status!(status, 'rw_page_fill')
+        nil
+      end
+    end
+
+    def title(options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, SIMPLE_TIMEOUT_KEYS, 'title options')
+      native_call do
+        out = @native.pointer_slot
+        status = @native.call(:rw_page_title, @handle, timeout(opts['timeout']), out)
+        @native.check_status!(status, 'rw_page_title')
+        @native.copy_owned_string(@native.pointer_address(out))
+      end
+    end
+
+    def text_content(selector, options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, SIMPLE_TIMEOUT_KEYS, 'text_content options')
+      selector = input_string(selector, 'selector')
+      native_call do
+        out = @native.pointer_slot
+        status = @native.call(:rw_page_text_content, @handle, selector, timeout(opts['timeout']), out)
+        @native.check_status!(status, 'rw_page_text_content')
+        @native.copy_owned_string(@native.pointer_address(out), nullable: true)
+      end
+    end
+
+    def evaluate(expression, argument = UNSET, options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, SIMPLE_TIMEOUT_KEYS, 'evaluate options')
+      expression = input_string(expression, 'expression')
+      argument_json = argument.equal?(UNSET) ? nil : JSON.generate(argument)
+      native_call do
+        out = @native.pointer_slot
+        status = @native.call(
+          :rw_page_evaluate,
+          @handle,
+          expression,
+          argument_json || 0,
+          timeout(opts['timeout']),
+          out
+        )
+        @native.check_status!(status, 'rw_page_evaluate')
+        json = @native.copy_owned_string(@native.pointer_address(out))
+        Wire.decode(JSON.parse(json))
+      end
+    end
+
+    def screenshot(options = nil, **keywords)
+      base = options || {}
+      raise ArgumentError, 'screenshot options must be a Hash' unless base.is_a?(Hash)
+
+      merged = base.merge(keywords)
+      normalized = Normalize.screenshot(merged)
+      options_json = normalized.nil? ? nil : JSON.generate(normalized)
+      native_call do
+        out_buffer = @native.pointer_slot
+        out_length = @native.size_slot
+        status = @native.call(
+          :rw_page_screenshot,
+          @handle,
+          options_json || 0,
+          out_buffer,
+          out_length
+        )
+        @native.check_status!(status, 'rw_page_screenshot')
+        @native.copy_owned_bytes(
+          @native.pointer_address(out_buffer),
+          @native.size_value(out_length)
+        )
+      end
+    end
+
+    def close(options = nil, **keywords)
+      opts = Normalize.option_hash(options, keywords, CLOSE_KEYS, 'close options')
+      @browser.synchronize do
+        @monitor.synchronize do
+          return nil if @handle.nil?
+
+          handle = @handle
+          begin
+            status = @native.call(
+              :rw_page_close,
+              handle,
+              timeout(opts['timeout']),
+              opts['run_before_unload'] ? 1 : 0
+            )
+            @native.check_status!(status, 'rw_page_close')
+          ensure
+            @native.call(:rw_page_free, handle)
+            @handle = nil
+            @browser.remove_page(self)
+          end
+        end
+      end
+      nil
+    end
+
+    def closed?
+      @browser.synchronize { @monitor.synchronize { @handle.nil? } }
+    end
+
+    private
+
+    def native_call
+      @browser.synchronize do
+        @monitor.synchronize do
+          raise ClosedError, 'page is closed' if @handle.nil?
+          raise ClosedError, 'browser is closed' if @browser.closed?
+
+          yield
+        end
+      end
+    end
+
+    def timeout(value)
+      return Float::NAN if value.nil?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "timeout must be numeric, got #{value.inspect}"
+    end
+
+    def input_string(value, name)
+      raise ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+
+      value.encode(Encoding::UTF_8)
+    end
+
+    def nullable_input_string(value, name)
+      value.nil? ? nil : input_string(value, name)
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: rustwright
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x86_64-linux
+authors:
+- Rustwright contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-03 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rustwright.rb
+- lib/rustwright/manifest.rb
+- lib/rustwright/native.rb
+- lib/rustwright/native/x86_64-linux/librustwright_capi.so
+- lib/rustwright/runner.rb
+- lib/rustwright/wire.rb
+homepage: https://github.com/Skyvern-AI/rustwright
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby bindings for the Rustwright browser automation C API
+test_files: []