wineole 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bdd93426e11cfe60fca09d51d9f12e32c5ea984767e18ec271a2ad6a471aba9
+  data.tar.gz: a04c2be3c95c7283e06327bea2b4e7725f4794351ab21439a8593fc0c4798693
+SHA512:
+  metadata.gz: 3cdd18036f72e3bd4d149c0fa71e9aab446cafa325936711bc2e5049584000431b9a224cd3c12cf508b6ac6d8c6f536039d4d86ea0adb94711dfc1f6f3e51dd2
+  data.tar.gz: 149e5ffe74bab247cf3849137956b425424a75598e2c6d24c54b36ecdabb6a2b8462eb58e12a73e75c7f7d3ae9da1ba170b1192c6249be00829bf4fbd29806d0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 firelzrd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/wineole/client.rb

@@ -0,0 +1,153 @@
+require 'socket'
+require 'json'
+require 'rbconfig'
+require 'tmpdir'
+require_relative 'errors'
+require_relative 'proxy'
+
+module WineOLE
+  class Client
+    WINDOWS = !(RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/).nil?
+
+    ARCH_TRIPLES = {
+      'x86_64' => 'x86_64-pc-windows-gnu',
+      'i386' => 'i686-pc-windows-gnu',
+      'i686' => 'i686-pc-windows-gnu',
+    }.freeze
+
+    def self.bridge_path_for_arch(host_cpu)
+      triple = ARCH_TRIPLES[host_cpu] || (ARCH_TRIPLES['i686'] if host_cpu =~ /^i.86$/)
+      if triple.nil?
+        raise Error, "no prebuilt wineole-bridge binary for host architecture #{host_cpu.inspect} " \
+                      "(available: #{ARCH_TRIPLES.values.uniq.join(', ')})"
+      end
+      File.expand_path("../../wineole-bridge-dist/#{triple}/wineole-bridge.exe", __dir__)
+    end
+
+    def self.default_bridge_path
+      bridge_path_for_arch(RbConfig::CONFIG['host_cpu'])
+    end
+
+    DEFAULT_SPAWNER = lambda do |port|
+      # wineole-bridge.exe is a native Windows binary either way -- `wine`
+      # is only needed to run it on a non-Windows host. On Windows itself
+      # there is no `wine` command, so running it under one would fail
+      # immediately (Errno::ENOENT) rather than run natively as it should.
+      # The null device path is also platform-specific ('/dev/null' does
+      # not exist on Windows).
+      command = WINDOWS ? [default_bridge_path] : ['wine', default_bridge_path]
+      null_device = WINDOWS ? 'NUL' : '/dev/null'
+      Process.spawn(*command, port.to_s, %i[out err] => null_device)
+    end
+
+    def self.default_lockfile(port)
+      # The lock is per-port, not global: two bridges on two ports are
+      # entirely independent, and a single shared lock would make a client
+      # starting one wait on a client starting the other (design doc §7.1
+      # step 2). Dir.tmpdir rather than a hardcoded '/tmp' resolves
+      # correctly on Windows (%TEMP%) as well as every POSIX platform.
+      File.join(Dir.tmpdir, "wineole-bridge.#{port}.lock")
+    end
+
+    def self.open(host: '127.0.0.1', port: 47800, spawner: DEFAULT_SPAWNER,
+                   lockfile: nil, timeout: 15, token: nil)
+      lockfile ||= default_lockfile(port)
+
+      socket = try_connect(host, port)
+      return handshake(new(socket), token) if socket
+
+      File.open(lockfile, File::CREAT | File::RDWR, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+
+        socket = try_connect(host, port)
+        return handshake(new(socket), token) if socket
+
+        spawner.call(port)
+        deadline = Time.now + timeout
+        loop do
+          socket = try_connect(host, port)
+          return handshake(new(socket), token) if socket
+          raise Error, "wineole-bridge did not start within #{timeout}s" if Time.now > deadline
+          sleep 0.2
+        end
+      end
+    end
+
+    # Design doc §7.1 step 1: ping after connecting, to confirm protocol
+    # compatibility before using the connection. This is also the only place a
+    # token can be presented — a bridge started with WINEOLE_TOKEN rejects
+    # every non-loopback request until a matching ping has been accepted, so
+    # without this a tokened bridge is unreachable from this client.
+    #
+    # A failed ping (bad token, incompatible bridge) raises out of
+    # `Client#call` as a RemoteError; it must not be swallowed.
+    def self.handshake(client, token)
+      client.call('ping', token ? {token: token} : {})
+      client
+    rescue StandardError
+      client.close
+      raise
+    end
+    private_class_method :handshake
+
+    def self.try_connect(host, port)
+      TCPSocket.new(host, port)
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EHOSTUNREACH
+      nil
+    end
+    private_class_method :try_connect
+
+    # A proc to close over the raw socket for ObjectSpace.define_finalizer.
+    # It deliberately does NOT close over `self` (the Client instance) --
+    # capturing the instance being finalized would keep it permanently
+    # reachable through ObjectSpace's own finalizer table, and it could
+    # never actually be collected. Capturing only the socket avoids this.
+    def self.finalizer(socket)
+      proc do
+        begin
+          socket.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    def initialize(socket)
+      @socket = socket
+      @next_id = 0
+      @mutex = Mutex.new
+      ObjectSpace.define_finalizer(self, self.class.finalizer(socket))
+    end
+
+    def call(method, params = {})
+      @mutex.synchronize do
+        id = (@next_id += 1)
+        @socket.write(JSON.generate({id: id, method: method, params: params}) + "\n")
+        line = @socket.gets
+        raise ProtocolError, 'connection closed' if line.nil?
+        response = JSON.parse(line)
+        unless response['id'] == id
+          raise ProtocolError, "id mismatch: expected #{id}, got #{response['id']}"
+        end
+        raise RemoteError.new(response['error']['class'], response['error']['message']) if response['error']
+        response['result']
+      end
+    end
+
+    def close
+      @socket.close
+    end
+
+    def create(class_name)
+      Proxy.create(class_name, self)
+    end
+
+    def connect(class_name)
+      Proxy.connect(class_name, self)
+    end
+
+    def connect_or_create(class_name)
+      Proxy.connect_or_create(class_name, self)
+    end
+  end
+end

data/lib/wineole/errors.rb

@@ -0,0 +1,15 @@
+module WineOLE
+  class Error < StandardError; end
+  class NotSerializableError < Error; end
+  class StaleReferenceError < Error; end
+  class ProtocolError < Error; end
+
+  class RemoteError < Error
+    attr_reader :remote_class
+
+    def initialize(remote_class, message)
+      @remote_class = remote_class
+      super("#{remote_class}: #{message}")
+    end
+  end
+end

data/lib/wineole/proxy.rb

@@ -0,0 +1,148 @@
+require 'time'
+require_relative 'errors'
+
+module WineOLE
+  class Proxy
+    def self.create(class_name, client)
+      handle = client.call('create', {class_name: class_name})['$ole_ref']
+      new(client, session_id: client.object_id, handle: handle, created: true)
+    end
+
+    def self.connect(class_name, client)
+      handle = client.call('connect', {class_name: class_name})['$ole_ref']
+      new(client, session_id: client.object_id, handle: handle, created: false)
+    end
+
+    def self.connect_or_create(class_name, client)
+      result = client.call('connect_or_create', {class_name: class_name})
+      new(client, session_id: client.object_id, handle: result['$ole_ref'], created: result['created'])
+    end
+
+    def self.wrap(client, session_id, ole_ref)
+      new(client, session_id: session_id, handle: ole_ref, created: nil)
+    end
+
+    # Ruby's implicit-conversion protocol. The interpreter probes these on
+    # arbitrary objects behind the scenes — `puts`/`p` and `Array()` look for
+    # `to_ary`/`to_a`, multiple assignment looks for `to_ary`, string
+    # interpolation and `Kernel#String` look for `to_str`, `IO` methods look
+    # for `to_io`, `&obj` looks for `to_proc`, `Integer()`/`format('%d', _)`/
+    # `"ab" * _`/array indexing look for `to_int`/`to_i`, `Float()` looks for
+    # `to_f`, `File.open` looks for `to_path`, and `1 + _` looks for `coerce`.
+    # Forwarding these to the remote object turns every `puts proxy` into a
+    # round trip that ends in DISP_E_UNKNOWNNAME, so they must behave exactly
+    # as they would on a plain Ruby object that doesn't define them:
+    # NoMethodError, and `respond_to?` == false (which is what stops the
+    # interpreter calling them at all).
+    IMPLICIT_CONVERSIONS = %i[
+      to_ary to_a to_hash to_str to_io to_proc
+      to_int to_i to_f to_path coerce
+    ].freeze
+
+    attr_reader :ole_handle, :ole_session_id
+
+    def initialize(client, session_id:, handle:, created:)
+      @client = client
+      @ole_session_id = session_id
+      @ole_handle = handle
+      @created = created
+    end
+
+    def method_missing(name, *args)
+      return super if IMPLICIT_CONVERSIONS.include?(name)
+
+      check_live!
+      named = args.last.is_a?(Hash) ? args.pop : {}
+      invoke(name.to_s, args, named)
+    end
+
+    def respond_to_missing?(name, _include_private = false)
+      !IMPLICIT_CONVERSIONS.include?(name)
+    end
+
+    def [](*args)
+      check_live!
+      invoke('', args, {})
+    end
+
+    # Was this instance freshly created by connect_or_create's
+    # fallback, or attached to something already running? `true` for
+    # `.create`, `false` for `.connect`, whatever the bridge reported for
+    # `.connect_or_create`, and `nil` for anything derived from another
+    # Proxy (e.g. `xl.Worksheets`) — attach-vs-create isn't a meaningful
+    # question for those.
+    def ole_created?
+      @created
+    end
+
+    def ole_release
+      @client.call('release', {handle: @ole_handle})
+    end
+
+    def ole_const_load
+      check_live!
+      @client.call('const_load', {handle: @ole_handle})
+    end
+
+    def marshal_dump
+      raise NotSerializableError, 'WineOLE::Proxy references are connection-scoped and cannot be persisted'
+    end
+
+    # Deliberately bare and public, unlike every other meta-method here
+    # (which are `ole_`-prefixed to avoid shadowing a same-named remote COM
+    # member): an explicit escape hatch for the rare case a COM object
+    # really does define e.g. an `ole_handle` member, matching real Ruby
+    # WIN32OLE's own choice to keep `invoke` public and unprefixed.
+    def invoke(name, args, named)
+      check_live!
+      params = {
+        handle: @ole_handle,
+        name: name,
+        args: args.map { |a| encode(a) },
+        named: named.transform_values { |v| encode(v) },
+      }
+      decode(@client.call('invoke', params))
+    end
+
+    private
+
+    def check_live!
+      return if @ole_session_id == @client.object_id
+
+      raise StaleReferenceError, 'this reference belongs to a previous connection'
+    end
+
+    def encode(value)
+      case value
+      when Proxy
+        # The argument's own liveness is not enough: a Proxy belonging to a
+        # *different* Client is live from its own point of view, yet its
+        # handle id means nothing in this connection's handle table (or,
+        # worse, means something unrelated). Check it against the receiver's
+        # client, which is the connection the id is about to be sent over.
+        unless value.ole_session_id == @client.object_id
+          raise StaleReferenceError,
+            'this reference belongs to a different connection and cannot be ' \
+            'passed as an argument here'
+        end
+        {'$ole_ref' => value.ole_handle}
+      when Hash
+        value.transform_values { |v| encode(v) }
+      when Array
+        value.map { |v| encode(v) }
+      else
+        value
+      end
+    end
+
+    def decode(value)
+      if value.is_a?(Hash) && value.key?('$ole_ref')
+        Proxy.wrap(@client, @client.object_id, value['$ole_ref'])
+      elsif value.is_a?(Hash) && value['$type'] == 'time'
+        Time.iso8601(value['iso8601'])
+      else
+        value
+      end
+    end
+  end
+end

data/lib/wineole.rb

@@ -0,0 +1,57 @@
+require_relative 'wineole/errors'
+require_relative 'wineole/client'
+require_relative 'wineole/proxy'
+
+module WineOLE
+  @default_client = nil
+  @mutex = Mutex.new
+
+  # Opens a client the same way Client.open does, and also makes it the
+  # module's implicit default -- a subsequent WineOLE.create/.connect call
+  # uses this client rather than lazily creating a separate zero-config one.
+  # Calling .open again replaces the implicit default without closing
+  # whatever it previously pointed to -- the caller owns the returned
+  # client and is responsible for closing it if not relying on the
+  # implicit default's eventual GC-finalizer cleanup.
+  def self.open(...)
+    client = Client.open(...)
+    @mutex.synchronize { @default_client = client }
+    client
+  end
+
+  # The lazily-initialized implicit default client used by .create/.connect
+  # when nothing was ever explicitly opened via WineOLE.open. Thread-safe:
+  # the fast path avoids locking once initialized; only the first caller(s)
+  # racing on a nil default contend for the lock, and only the actual
+  # winner calls Client.open -- everyone else sees it already set once they
+  # acquire the lock, and the `||=` means they never call Client.open again.
+  def self.default_client
+    return @default_client if @default_client
+
+    @mutex.synchronize { @default_client ||= Client.open }
+  end
+  private_class_method :default_client
+
+  def self.create(class_name)
+    default_client.create(class_name)
+  end
+
+  def self.connect(class_name)
+    default_client.connect(class_name)
+  end
+
+  def self.connect_or_create(class_name)
+    default_client.connect_or_create(class_name)
+  end
+
+  # Closes the implicit default client, if one exists, and clears it so the
+  # next .create/.connect lazily opens a fresh one. Mainly for test hygiene
+  # (clearing state between test cases); also usable to release the
+  # implicit default early in a long-running process.
+  def self.close
+    @mutex.synchronize do
+      @default_client&.close
+      @default_client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: wineole
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- firelzrd
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A bridge (Rust, cross-compiled to run under Wine) plus a Ruby client
+  that lets a Linux Ruby process drive Win32OLE/COM automation of
+  Windows applications running under Wine, over a JSON Lines TCP
+  protocol, without requiring a Windows build of Ruby.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/wineole.rb
+- lib/wineole/client.rb
+- lib/wineole/errors.rb
+- lib/wineole/proxy.rb
+- wineole-bridge-dist/aarch64-pc-windows-gnullvm/wineole-bridge.exe
+- wineole-bridge-dist/i686-pc-windows-gnu/wineole-bridge.exe
+- wineole-bridge-dist/x86_64-pc-windows-gnu/wineole-bridge.exe
+homepage: https://github.com/firelzrd/wineole
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/firelzrd/wineole
+  bug_tracker_uri: https://github.com/firelzrd/wineole/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Drive Win32OLE/COM automation of Wine-hosted Windows apps from Ruby
+test_files: []