ruby-dbus 0.22.1 → 0.23.0.beta2

data/lib/dbus/object_server.rb

@@ -0,0 +1,149 @@
+# 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,nil]
+    def object(path)
+      node = get_node(path, create: false)
+      node&.object
+    end
+    alias [] object
+
+    # Export an object
+    # @param obj [DBus::Object]
+    # @raise RuntimeError if there's already an exported object at the same path
+    def export(obj)
+      node = get_node(obj.path, create: true)
+      raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
+
+      node.object = obj
+
+      obj.object_server = self
+      object_manager_for(obj)&.object_added(obj)
+    end
+
+    # Undo exporting an object *obj_or_path*.
+    # Raises ArgumentError if it is not a DBus::Object.
+    # Returns the object, or false if _obj_ was not exported.
+    # @param obj_or_path [DBus::Object,ObjectPath,String] an object or a valid object path
+    def unexport(obj_or_path)
+      path = self.class.path_of(obj_or_path)
+      parent_path, _separator, node_name = path.rpartition("/")
+
+      parent_node = get_node(parent_path, create: false)
+      return false unless parent_node
+
+      node = if node_name == "" # path == "/"
+               parent_node
+             else
+               parent_node[node_name]
+             end
+      obj = node&.object
+      raise ArgumentError, "Cannot unexport, no object at #{path}" unless obj
+
+      object_manager_for(obj)&.object_removed(obj)
+      obj.object_server = nil
+      node.object = nil
+
+      # node can be deleted if
+      # - it has no children
+      # - it is not root
+      if node.empty? && !node.equal?(parent_node)
+        parent_node.delete(node_name)
+      end
+
+      obj
+    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
+
+    # @param obj_or_path [DBus::Object,ObjectPath,String] an object or a valid object path
+    # @return [ObjectPath]
+    # @api private
+    def self.path_of(obj_or_path)
+      case obj_or_path
+      when ObjectPath
+        obj_or_path
+      when String
+        ObjectPath.new(obj_or_path)
+      when DBus::Object
+        obj_or_path.path
+      else
+        raise ArgumentError, "Expecting a DBus::Object argument or DBus::ObjectPath or String which parses as one"
+      end
+    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/org.freedesktop.DBus.xml

@@ -0,0 +1,97 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.freedesktop.DBus">
+    <method name="Hello">
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="RequestName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="ReleaseName">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="StartServiceByName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="UpdateActivationEnvironment">
+      <arg direction="in" type="a{ss}"/>
+    </method>
+    <method name="NameHasOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="b"/>
+    </method>
+    <method name="ListNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="ListActivatableNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="AddMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="RemoveMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="GetNameOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="ListQueuedOwners">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="GetConnectionUnixUser">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetConnectionUnixProcessID">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetAdtAuditSessionData">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="ay"/>
+    </method>
+    <method name="GetConnectionSELinuxSecurityContext">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="ay"/>
+    </method>
+    <method name="ReloadConfig">
+    </method>
+    <method name="GetId">
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="GetConnectionCredentials">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="a{sv}"/>
+    </method>
+    <property name="Features" type="as" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
+    </property>
+    <property name="Interfaces" type="as" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="const"/>
+    </property>
+    <signal name="NameOwnerChanged">
+      <arg type="s"/>
+      <arg type="s"/>
+      <arg type="s"/>
+    </signal>
+    <signal name="NameLost">
+      <arg type="s"/>
+    </signal>
+    <signal name="NameAcquired">
+      <arg type="s"/>
+    </signal>
+  </interface>
+</node>

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,107 @@
+# 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.
+    # Will be nil for a {PeerConnection}
+    attr_reader :name
+    # @return [Connection] The connection we're using.
+    attr_reader :connection
+
+    # @param connection [Connection] The connection we're using.
+    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 = connection.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
+
+  # A hack for pretending that a {PeerConnection} has a single unnamed {ProxyService}
+  # so that we can get {ProxyObject}s from it.
+  class ProxyPeerService < ProxyService
+    # @param connection [Connection] The peer connection we're using.
+    def initialize(connection)
+      # this way we disallow ProxyService taking a nil name by accident
+      super(":0.0", connection)
+      @name = nil
+    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
 
@@ -29,22 +26,27 @@ require_relative "dbus/api_options"
 require_relative "dbus/auth"
 require_relative "dbus/bus"
 require_relative "dbus/bus_name"
+require_relative "dbus/connection"
 require_relative "dbus/data"
 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/ruby-dbus.gemspec

@@ -9,7 +9,7 @@ GEMSPEC = Gem::Specification.new do |s|
   s.summary = "Ruby module for interaction with D-Bus"
   s.description = "Pure Ruby module for interaction with D-Bus IPC system"
   s.version = File.read("VERSION").strip
-  s.license = "LGPL-2.1"
+  s.license = "LGPL-2.1-or-later"
   s.author = "Ruby DBus Team"
   s.email = "martin.github@vidner.net"
   s.homepage = "https://github.com/mvidner/ruby-dbus"

data/spec/bus_connection_spec.rb

@@ -0,0 +1,80 @@
+#!/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
+
+    # This only works with our special bus setup
+    context "when we're not allowed to own the name", tag_limited_bus: true do
+      it "raises an error... too late" do
+        name = "org.rubygems.ruby_dbus.NobodyCanOwnThisName"
+        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_limited_bus: true do
+      it "raises an error" do
+        name = "org.rubygems.ruby_dbus.NobodyCanOwnThisName"
+        expect do
+          bus.request_name(name)
+        end.to raise_error(DBus::Error, /not allowed to own the service/)
+      end
+    end
+  end
+end

data/spec/connection_spec.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env rspec
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require "dbus"
+
+describe DBus::PeerConnection do
+  let(:address) { ENV["DBUS_SESSION_BUS_ADDRESS"] }
+  subject { described_class.new(address) }
+
+  describe "#peer_service" do
+    it "returns a PeerService with a nil name" do
+      svc = subject.peer_service
+      expect(svc).to be_a(DBus::ProxyService)
+      expect(svc.name).to be_nil
+    end
+  end
+
+  describe "#add_match, #remove_match" do
+    it "doesn't crash trying to call AddMatch, RemoveMatch" do
+      mr = DBus::MatchRule.new
+      mr.member = "StateUpdated"
+      mr.interface = "org.PulseAudio.Core1.Device"
+      handler = ->(_msg) {}
+
+      # Cheating a bit with the mocking:
+      # a PulseAudio peer connection would error with
+      # > DBus::Error: Method "AddMatch" with signature "s" on interface
+      # > "org.freedesktop.DBus" doesn't exist
+      # but here we do have a bus at the other end, which replies with
+      # > DBus::Error: Client tried to send a message other than Hello without being registered
+      # where "registering" is a libdbus-1 thing meaning "internal bookkeeping and send Hello"
+      expect { subject.add_match(mr, &handler) }.to_not raise_error
+      expect { subject.remove_match(mr) }.to_not raise_error
+    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/dbus_spec.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env rspec
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require "dbus"
+
+describe DBus do
+  describe ".session_bus", tag_bus: true do
+    it "returns a BusConnection" do
+      expect(DBus.session_bus).to be_a(DBus::BusConnection)
+    end
+  end
+
+  describe ".system_bus" do
+    # coverage obsession: mock it out,
+    # system bus may not exist during RPM builds
+    it "calls SystemBus.instance" do
+      expect(DBus::SystemBus).to receive(:instance)
+      DBus.system_bus
+    end
+  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