ruby-dbus 0.22.0 → 0.23.0.beta1

data/lib/dbus/node_tree.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+# Copyright (C) 2023 Martin Vidner
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+module DBus
+  # Has a tree of {Node}s, refering to {Object}s or to {ProxyObject}s.
+  class NodeTree
+    # @return [Node]
+    attr_reader :root
+
+    def initialize
+      @root = Node.new("/")
+    end
+
+    # Get the object node corresponding to the given *path*.
+    # @param path [ObjectPath]
+    # @param create [Boolean] if true, the the {Node}s in the path are created
+    #   if they do not already exist.
+    # @return [Node,nil]
+    def get_node(path, create: false)
+      n = @root
+      path.sub(%r{^/}, "").split("/").each do |elem|
+        if !(n[elem])
+          return nil if !create
+
+          n[elem] = Node.new(elem)
+        end
+        n = n[elem]
+      end
+      n
+    end
+  end
+
+  # = Object path node class
+  #
+  # Class representing a node on an object path.
+  class Node < Hash
+    # @return [DBus::Object,DBus::ProxyObject,nil]
+    #   The D-Bus object contained by the node.
+    attr_accessor :object
+
+    # The name of the node.
+    # @return [String] the last component of its object path, or "/"
+    attr_reader :name
+
+    # Create a new node with a given _name_.
+    def initialize(name)
+      super()
+      @name = name
+      @object = nil
+    end
+
+    # Return an XML string representation of the node.
+    # It is shallow, not recursing into subnodes
+    # @param node_opath [String]
+    def to_xml(node_opath)
+      xml = '<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+'
+      xml += "<node name=\"#{node_opath}\">\n"
+      each_key do |k|
+        xml += "  <node name=\"#{k}\" />\n"
+      end
+      @object&.intfs&.each_value do |v|
+        xml += v.to_xml
+      end
+      xml += "</node>"
+      xml
+    end
+
+    # Return inspect information of the node.
+    def inspect
+      # Need something here
+      "<DBus::Node #{sub_inspect}>"
+    end
+
+    # Return instance inspect information, used by Node#inspect.
+    def sub_inspect
+      s = ""
+      if !@object.nil?
+        s += format("%x ", @object.object_id)
+      end
+      contents_sub_inspect = keys
+                             .map { |k| "#{k} => #{self[k].sub_inspect}" }
+                             .join(",")
+      "#{s}{#{contents_sub_inspect}}"
+    end
+
+    # All objects (not paths) under this path (except itself).
+    # @return [Array<DBus::Object>]
+    def descendant_objects
+      children_objects = values.map(&:object).compact
+      descendants = values.map(&:descendant_objects)
+      flat_descendants = descendants.reduce([], &:+)
+      children_objects + flat_descendants
+    end
+  end
+end

data/lib/dbus/object.rb

@@ -26,20 +26,29 @@ module DBus
     my_class_attribute :intfs
     self.intfs = {}
 
-    # The service that the object is exported by.
-    attr_writer :service
+    # @return [Connection] the connection the object is exported by
+    attr_reader :connection
 
     @@cur_intf = nil # Interface
     @@intfs_mutex = Mutex.new
 
     # Create a new object with a given _path_.
-    # Use Service#export to export it.
+    # Use ObjectServer#export to export it.
     def initialize(path)
       @path = path
-      @service = nil
+      @connection = nil
+    end
+
+    # @param connection [Connection] the connection the object is exported by
+    def connection=(connection)
+      @connection = connection
+      # deprecated, keeping @service for compatibility
+      @service = connection&.object_server
     end
 
     # Dispatch a message _msg_ to call exported methods
+    # @param msg [Message] only METHOD_CALLS do something
+    # @api private
     def dispatch(msg)
       case msg.message_type
       when Message::METHOD_CALL
@@ -69,7 +78,7 @@ module DBus
           dbus_msg_exc = msg.annotate_exception(e)
           reply = ErrorMessage.from_exception(dbus_msg_exc).reply_to(msg)
         end
-        @service.bus.message_queue.push(reply)
+        @connection.message_queue.push(reply)
       end
     end
 
@@ -307,7 +316,7 @@ module DBus
     # @param sig [Signal]
     # @param args arguments for the signal
     def emit(intf, sig, *args)
-      @service.bus.emit(@service, self, intf, sig, *args)
+      @connection.emit(nil, self, intf, sig, *args)
     end
 
     # Defines a signal for the object with a given name _sym_ and _prototype_.
@@ -316,7 +325,7 @@ module DBus
 
       cur_intf = @@cur_intf
       signal = Signal.new(sym.to_s).from_prototype(prototype)
-      cur_intf.define(Signal.new(sym.to_s).from_prototype(prototype))
+      cur_intf.define(signal)
 
       # ::Module#define_method(name) { body }
       define_method(sym.to_s) do |*args|

data/lib/dbus/object_manager.rb

@@ -14,7 +14,7 @@ module DBus
   # {https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager
   # org.freedesktop.DBus.ObjectManager}.
   #
-  # {Service#export} and {Service#unexport} will look for an ObjectManager
+  # {ObjectServer#export} and {ObjectServer#unexport} will look for an ObjectManager
   # parent in the path hierarchy. If found, it will emit InterfacesAdded
   # or InterfacesRemoved, as appropriate.
   module ObjectManager
@@ -23,8 +23,7 @@ module DBus
     # @return [Hash{ObjectPath => Hash{String => Hash{String => Data::Base}}}]
     #   object -> interface -> property -> value
     def managed_objects
-      # FIXME: also fix the "service" concept
-      descendant_objects = @service.descendants_for(path)
+      descendant_objects = connection.object_server.descendants_for(path)
       descendant_objects.each_with_object({}) do |obj, hash|
         hash[obj.path] = obj.interfaces_and_properties
       end

data/lib/dbus/object_server.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+# Copyright (C) 2023 Martin Vidner
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+require_relative "node_tree"
+
+module DBus
+  # The part of a {Connection} that can export {DBus::Object}s to provide
+  # services to clients.
+  #
+  # Note that an ObjectServer does not have a name. Typically a {Connection}
+  # has one well known name, but can have none or more.
+  #
+  # Formerly this class was intermixed with {ProxyService} as Service.
+  #
+  # @example Usage
+  #   bus = DBus.session_bus
+  #   obj = DBus::Object.new("/path") # a subclass more likely
+  #   bus.object_server.export(obj)
+  #   bus.request_name("org.example.Test")
+  class ObjectServer < NodeTree
+    # @return [Connection] The connection we're using.
+    attr_reader :connection
+
+    def initialize(connection)
+      @connection = connection
+      super()
+    end
+
+    # Retrieves an object at the given _path_
+    # @param path [ObjectPath]
+    # @return [DBus::Object]
+    def object(path)
+      node = get_node(path, create: false)
+      node&.object
+    end
+    alias [] object
+
+    # Export an object
+    # @param obj [DBus::Object]
+    def export(obj)
+      node = get_node(obj.path, create: true)
+      # TODO: clarify that this is indeed the right thing, and document
+      # raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
+
+      node.object = obj
+
+      obj.connection = @connection
+      object_manager_for(obj)&.object_added(obj)
+    end
+
+    # Undo exporting an object _obj_.
+    # Raises ArgumentError if it is not a DBus::Object.
+    # Returns the object, or false if _obj_ was not exported.
+    # @param obj [DBus::Object]
+    def unexport(obj)
+      raise ArgumentError, "Expecting a DBus::Object argument" unless obj.is_a?(DBus::Object)
+
+      last_path_separator_idx = obj.path.rindex("/")
+      parent_path = obj.path[1..last_path_separator_idx - 1]
+      node_name = obj.path[last_path_separator_idx + 1..-1]
+
+      parent_node = get_node(parent_path, create: false)
+      return false unless parent_node
+
+      object_manager_for(obj)&.object_removed(obj)
+      obj.connection = nil
+      parent_node.delete(node_name).object
+    end
+
+    # Find the (closest) parent of *object*
+    # implementing the ObjectManager interface, or nil
+    # @return [DBus::Object,nil]
+    def object_manager_for(object)
+      path = object.path
+      node_chain = get_node_chain(path)
+      om_node = node_chain.reverse_each.find do |node|
+        node.object&.is_a? DBus::ObjectManager
+      end
+      om_node&.object
+    end
+
+    # All objects (not paths) under this path (except itself).
+    # @param path [ObjectPath]
+    # @return [Array<DBus::Object>]
+    # @raise ArgumentError if the *path* does not exist
+    def descendants_for(path)
+      node = get_node(path, create: false)
+      raise ArgumentError, "Object path #{path} doesn't exist" if node.nil?
+
+      node.descendant_objects
+    end
+
+    #########
+
+    private
+
+    #########
+
+    # @param path [ObjectPath] a path that must exist
+    # @return [Array<Node>] nodes from the root to the leaf
+    def get_node_chain(path)
+      n = @root
+      result = [n]
+      path.sub(%r{^/}, "").split("/").each do |elem|
+        n = n[elem]
+        result.push(n)
+      end
+      result
+    end
+  end
+end

data/lib/dbus/proxy_object.rb

@@ -10,20 +10,20 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # D-Bus proxy object class
-  #
-  # Class representing a remote object in an external application.
+  # Represents a remote object in an external application.
   # Typically, calling a method on an instance of a ProxyObject sends a message
-  # over the bus so that the method is executed remotely on the correctponding
+  # over the bus so that the method is executed remotely on the corresponding
   # object.
   class ProxyObject
     # The names of direct subnodes of the object in the tree.
     attr_accessor :subnodes
     # Flag determining whether the object has been introspected.
+    # @return [Boolean]
     attr_accessor :introspected
     # The (remote) destination of the object.
     attr_reader :destination
     # The path to the object.
+    # @return [ObjectPath]
     attr_reader :path
     # The bus the object is reachable via.
     attr_reader :bus

data/lib/dbus/proxy_service.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+# Copyright (C) 2023 Martin Vidner
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+require_relative "node_tree"
+
+module DBus
+  # Used by clients to represent a named service on the other side of the bus.
+  #
+  # Formerly this class was intermixed with {ObjectServer} as Service.
+  #
+  # @example Usage
+  #   svc = DBus.system_bus["org.freedesktop.machine1"]
+  #   manager = svc["/org/freedesktop/machine1"]
+  #   p manager.ListImages
+  class ProxyService < NodeTree
+    # @return [BusName,nil] The service name.
+    # May be nil for peer connections
+    attr_reader :name
+    # @return [Connection] The connection we're using.
+    attr_reader :connection
+
+    def initialize(name, connection)
+      @name = BusName.new(name)
+      @connection = connection
+      super()
+    end
+
+    # Determine whether the service name already exists.
+    def exists?
+      bus = connection # TODO: raise a better error if this is a peer connection
+      bus.proxy.ListNames[0].member?(@name)
+    end
+
+    # Perform an introspection on all the objects on the service
+    # (starting recursively from the root).
+    def introspect
+      raise NotImplementedError if block_given?
+
+      rec_introspect(@root, "/")
+      self
+    end
+
+    # Retrieves an object at the given _path_.
+    # @param path [ObjectPath]
+    # @return [ProxyObject]
+    def [](path)
+      object(path, api: ApiOptions::A1)
+    end
+
+    # Retrieves an object at the given _path_
+    # whose methods always return an array.
+    # @param path [ObjectPath]
+    # @param api [ApiOptions]
+    # @return [ProxyObject]
+    def object(path, api: ApiOptions::A0)
+      node = get_node(path, create: true)
+      if node.object.nil? || node.object.api != api
+        node.object = ProxyObject.new(
+          @connection, @name, path,
+          api: api
+        )
+      end
+      node.object
+    end
+
+    private
+
+    # Perform a recursive retrospection on the given current _node_
+    # on the given _path_.
+    def rec_introspect(node, path)
+      xml = bus.introspect_data(@name, path)
+      intfs, subnodes = IntrospectXMLParser.new(xml).parse
+      subnodes.each do |nodename|
+        subnode = node[nodename] = Node.new(nodename)
+        subpath = if path == "/"
+                    "/#{nodename}"
+                  else
+                    "#{path}/#{nodename}"
+                  end
+        rec_introspect(subnode, subpath)
+      end
+      return if intfs.empty?
+
+      node.object = ProxyObjectFactory.new(xml, @connection, @name, path).build
+    end
+  end
+end

data/lib/dbus.rb

@@ -11,17 +11,14 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # Byte signifying big endianness.
+  # Protocol character signifying big endianness.
   BIG_END = "B"
-  # Byte signifying little endianness.
+  # Protocol character signifying little endianness.
   LIL_END = "l"
 
-  # Byte signifying the host's endianness.
-  HOST_END = if [0x01020304].pack("L").unpack1("V") == 0x01020304
-               LIL_END
-             else
-               BIG_END
-             end
+  # Protocol character signifying the host's endianness.
+  # "S": unpack as uint16, native endian
+  HOST_END = { 1 => BIG_END, 256 => LIL_END }.fetch("\x00\x01".unpack1("S"))
 end
 # ^ That's because dbus/message needs HOST_END early
 
@@ -34,17 +31,21 @@ require_relative "dbus/emits_changed_signal"
 require_relative "dbus/error"
 require_relative "dbus/introspect"
 require_relative "dbus/logger"
+require_relative "dbus/main"
 require_relative "dbus/marshall"
 require_relative "dbus/matchrule"
 require_relative "dbus/message"
 require_relative "dbus/message_queue"
+require_relative "dbus/node_tree"
 require_relative "dbus/object"
 require_relative "dbus/object_manager"
 require_relative "dbus/object_path"
+require_relative "dbus/object_server"
 require_relative "dbus/platform"
 require_relative "dbus/proxy_object"
 require_relative "dbus/proxy_object_factory"
 require_relative "dbus/proxy_object_interface"
+require_relative "dbus/proxy_service"
 require_relative "dbus/raw_message"
 require_relative "dbus/type"
 require_relative "dbus/xml"

data/spec/bus_connection_spec.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env rspec
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require "dbus"
+
+describe DBus::BusConnection do
+  let(:bus) { DBus::ASessionBus.new }
+
+  # deprecated method
+  describe "#request_service", tag_bus: true, tag_deprecated: true do
+    context "when the name request succeeds" do
+      # Formerly it returned Service, now ObjectServer takes its role.
+      # Replacement: server = bus.object_server; bus.request_name(name)
+      it "returns something which can export objects" do
+        name = "org.rubygems.ruby_dbus.RequestServiceTest"
+        server = bus.request_service(name)
+        expect(server).to respond_to(:export)
+        bus.proxy.ReleaseName(name)
+      end
+    end
+
+    context "when the name is taken already", tag_service: true do
+      # formerly it returned Service, now ObjectServer takes its role
+      it "raises NameRequestError... too late" do
+        name = "org.ruby.service"
+        expect do
+          bus.request_service(name)
+          _unrelated_call = bus.proxy.GetId.first
+        end.to raise_error(DBus::Connection::NameRequestError)
+        # The call fails but it means we did not get the name RIGHT AWAY
+        # but we are still queued to get it as soon as the current owner
+        # gives it up.
+        # So even now we have to the bus to remove us from the queue
+        bus.proxy.ReleaseName(name)
+      end
+    end
+
+    context "when we're not allowed to own the name", tag_system_bus: true do
+      let(:bus) { DBus::ASystemBus.new }
+      xit "raises an error... too late" do
+        name = "org.rubygems.ruby_dbus.NotAllowedToOwnThisNameAnyway"
+        expect do
+          bus.request_service(name)
+          _unrelated_call = bus.proxy.GetId.first
+        end.to raise_error(DBus::Error, /not allowed to own the service/)
+      end
+    end
+  end
+
+  describe "#request_name", tag_bus: true do
+    context "when the name request succeeds" do
+      it "returns something which can export objects" do
+        name = "org.rubygems.ruby_dbus.RequestNameTest"
+        expect { bus.request_name(name) }.to_not raise_error
+        bus.proxy.ReleaseName(name)
+      end
+    end
+
+    context "when the name is taken already", tag_service: true do
+      # formerly it returned Service, now ObjectServer takes its role
+      it "raises NameRequestError" do
+        name = "org.ruby.service"
+        expect do
+          # flags: avoid getting the name sometime later, unexpectedly
+          bus.request_name(name, flags: DBus::Connection::NAME_FLAG_DO_NOT_QUEUE)
+        end.to raise_error(DBus::Connection::NameRequestError)
+      end
+    end
+
+    context "when we're not allowed to own the name", tag_system_bus: true do
+      let(:bus) { DBus::ASystemBus.new }
+      xit "raises an error... too late" do
+        name = "org.rubygems.ruby_dbus.NotAllowedToOwnThisNameAnyway"
+        expect do
+          bus.request_name(name)
+        end.to raise_error(DBus::Error, /not allowed to own the service/)
+      end
+    end
+  end
+end

data/spec/coverage_helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+coverage = if ENV["COVERAGE"]
+             ENV["COVERAGE"] == "true"
+           else
+             # heuristics: enable for interactive builds (but not in OBS)
+             ENV["DISPLAY"]
+           end
+
+if coverage
+  require "simplecov"
+  SimpleCov.root File.expand_path("..", __dir__)
+
+  # do not cover specs
+  SimpleCov.add_filter "_spec.rb"
+  # do not cover the activesupport helpers
+  SimpleCov.add_filter "/core_ext/"
+  # measure all if/else branches on a line
+  SimpleCov.enable_coverage :branch
+
+  SimpleCov.start
+
+  # additionally use the LCOV format for on-line code coverage reporting at CI
+  if ENV["COVERAGE_LCOV"] == "true"
+    require "simplecov-lcov"
+
+    SimpleCov::Formatter::LcovFormatter.config do |c|
+      c.report_with_single_file = true
+      # this is the default Coveralls GitHub Action location
+      # https://github.com/marketplace/actions/coveralls-github-action
+      c.single_report_path = "coverage/lcov.info"
+    end
+
+    SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::LcovFormatter
+    ]
+  end
+end

data/spec/main_loop_spec.rb

@@ -5,6 +5,20 @@
 require_relative "spec_helper"
 require "dbus"
 
+describe "DBus.logger" do
+  it "will log debug messages if $DEBUG is true" do
+    logger_old = DBus.logger
+    DBus.logger = nil
+    debug_old = $DEBUG
+    $DEBUG = true
+
+    DBus.logger.debug "this debug message will always be shown"
+
+    $DEBUG = debug_old
+    DBus.logger = logger_old
+  end
+end
+
 describe "MainLoopTest" do
   before(:each) do
     @session_bus = DBus::ASessionBus.new

data/spec/message_spec.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env rspec
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require "dbus"
+
+# Pedantic full coverage test.
+# The happy paths are covered via calling classes
+describe DBus::Message do
+  describe "#marshall" do
+    it "raises when the object path is /org/freedesktop/DBus/Local" do
+      m = DBus::Message.new(DBus::Message::SIGNAL)
+      # the path is valid, it just must not be sent
+      m.path = DBus::ObjectPath.new("/org/freedesktop/DBus/Local")
+      m.interface = "org.example.spam"
+      m.member = "Spam"
+
+      expect { m.marshall }.to raise_error(RuntimeError, /Cannot send a message with the reserved path/)
+    end
+  end
+end

data/spec/mock-service/cockpit-dbustests.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../coverage_helper"
+SimpleCov.command_name "Cockpit Tests (#{Process.pid})" if Object.const_defined? "SimpleCov"
+
+# find the library without external help
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "dbus"
+
+SERVICE_NAME = "org.rubygems.ruby_dbus.DBusTests"
+ROOT_OPATH = "/otree/frobber"
+
+class DBusTests < DBus::Object
+  FROBBER_INTERFACE = "com.redhat.Cockpit.DBusTests.Frobber"
+
+  dbus_interface FROBBER_INTERFACE do
+    dbus_method :HelloWorld, "in greeting:s, out response:s" do |greeting|
+      # TODO: return the same thing as the original implementation
+      # and try substituting it?
+      [format("Word! You said `%s'. I'm Skeleton, btw!", greeting)]
+    end
+  end
+end
+
+bus = DBus::SessionBus.instance
+bus.object_server.export(DBusTests.new(ROOT_OPATH))
+bus.request_name(SERVICE_NAME)
+DBus::Main.new.tap { |m| m << bus }.run