ruby-dbus 0.23.0.beta1 → 0.23.0.beta2

data/lib/dbus/connection.rb

@@ -0,0 +1,350 @@
+# 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
+  # D-Bus main connection class
+  #
+  # Main class that maintains a connection to a bus and can handle incoming
+  # and outgoing messages.
+  class Connection
+    # pop and push messages here
+    # @return [MessageQueue]
+    attr_reader :message_queue
+
+    # Create a new connection to the bus for a given connect _path_. _path_
+    # format is described in the D-Bus specification:
+    # http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
+    # and is something like:
+    # "transport1:key1=value1,key2=value2;transport2:key1=value1,key2=value2"
+    # e.g. "unix:path=/tmp/dbus-test" or "tcp:host=localhost,port=2687"
+    def initialize(path)
+      @message_queue = MessageQueue.new(path)
+
+      # @return [Hash{Integer => Proc}]
+      #   key: message serial
+      #   value: block to be run when the reply to that message is received
+      @method_call_replies = {}
+
+      # @return [Hash{Integer => Message}]
+      #   for debugging only: messages for which a reply was not received yet;
+      #   key == value.serial
+      @method_call_msgs = {}
+      @signal_matchrules = {}
+    end
+
+    def object_server
+      @object_server ||= ObjectServer.new(self)
+    end
+
+    # Dispatch all messages that are available in the queue,
+    # but do not block on the queue.
+    # Called by a main loop when something is available in the queue
+    def dispatch_message_queue
+      while (msg = @message_queue.pop(blocking: false)) # FIXME: EOFError
+        process(msg)
+      end
+    end
+
+    # Tell a bus to register itself on the glib main loop
+    def glibize
+      require "glib2"
+      # Circumvent a ruby-glib bug
+      @channels ||= []
+
+      gio = GLib::IOChannel.new(@message_queue.socket.fileno)
+      @channels << gio
+      gio.add_watch(GLib::IOChannel::IN) do |_c, _ch|
+        dispatch_message_queue
+        true
+      end
+    end
+
+    # NAME_FLAG_* and REQUEST_NAME_* belong to BusConnection
+    # but users will have referenced them in Connection so they need to stay here
+
+    # FIXME: describe the following names, flags and constants.
+    # See DBus spec for definition
+    NAME_FLAG_ALLOW_REPLACEMENT = 0x1
+    NAME_FLAG_REPLACE_EXISTING = 0x2
+    NAME_FLAG_DO_NOT_QUEUE = 0x4
+
+    REQUEST_NAME_REPLY_PRIMARY_OWNER = 0x1
+    REQUEST_NAME_REPLY_IN_QUEUE = 0x2
+    REQUEST_NAME_REPLY_EXISTS = 0x3
+    REQUEST_NAME_REPLY_ALREADY_OWNER = 0x4
+
+    # @api private
+    # Send a _message_.
+    # If _reply_handler_ is not given, wait for the reply
+    # and return the reply, or raise the error.
+    # If _reply_handler_ is given, it will be called when the reply
+    # eventually arrives, with the reply message as the 1st param
+    # and its params following
+    def send_sync_or_async(message, &reply_handler)
+      ret = nil
+      if reply_handler.nil?
+        send_sync(message) do |rmsg|
+          raise rmsg if rmsg.is_a?(Error)
+
+          ret = rmsg.params
+        end
+      else
+        on_return(message) do |rmsg|
+          if rmsg.is_a?(Error)
+            reply_handler.call(rmsg)
+          else
+            reply_handler.call(rmsg, * rmsg.params)
+          end
+        end
+        @message_queue.push(message)
+      end
+      ret
+    end
+
+    # @api private
+    def introspect_data(dest, path, &reply_handler)
+      m = DBus::Message.new(DBus::Message::METHOD_CALL)
+      m.path = path
+      m.interface = "org.freedesktop.DBus.Introspectable"
+      m.destination = dest
+      m.member = "Introspect"
+      m.sender = unique_name
+      if reply_handler.nil?
+        send_sync_or_async(m).first
+      else
+        send_sync_or_async(m) do |*args|
+          # TODO: test async introspection, is it used at all?
+          args.shift # forget the message, pass only the text
+          reply_handler.call(*args)
+          nil
+        end
+      end
+    end
+
+    # @api private
+    # Issues a call to the org.freedesktop.DBus.Introspectable.Introspect method
+    # _dest_ is the service and _path_ the object path you want to introspect
+    # If a code block is given, the introspect call in asynchronous. If not
+    # data is returned
+    #
+    # FIXME: link to ProxyObject data definition
+    # The returned object is a ProxyObject that has methods you can call to
+    # issue somme METHOD_CALL messages, and to setup to receive METHOD_RETURN
+    def introspect(dest, path)
+      if !block_given?
+        # introspect in synchronous !
+        data = introspect_data(dest, path)
+        pof = DBus::ProxyObjectFactory.new(data, self, dest, path)
+        pof.build
+      else
+        introspect_data(dest, path) do |async_data|
+          yield(DBus::ProxyObjectFactory.new(async_data, self, dest, path).build)
+        end
+      end
+    end
+
+    # Exception raised when a service name is requested that is not available.
+    class NameRequestError < Exception
+    end
+
+    def handle_return_of_request_name(ret, name)
+      details = if ret == REQUEST_NAME_REPLY_IN_QUEUE
+                  other = proxy.GetNameOwner(name).first
+                  other_creds = proxy.GetConnectionCredentials(other).first
+                  "already owned by #{other}, #{other_creds.inspect}"
+                else
+                  "error code #{ret}"
+                end
+      raise NameRequestError, "Could not request #{name}, #{details}" unless ret == REQUEST_NAME_REPLY_PRIMARY_OWNER
+
+      ret
+    end
+
+    # Attempt to request a service _name_.
+    # @raise NameRequestError which cannot really be rescued as it will be raised when dispatching a later call.
+    # @return [ObjectServer]
+    # @deprecated Use {BusConnection#request_name}.
+    def request_service(name)
+      # Use RequestName, but asynchronously!
+      # A synchronous call would not work with service activation, where
+      # method calls to be serviced arrive before the reply for RequestName
+      # (Ticket#29).
+      proxy.RequestName(name, NAME_FLAG_REPLACE_EXISTING) do |rmsg, r|
+        # check and report errors first
+        raise rmsg if rmsg.is_a?(Error)
+
+        handle_return_of_request_name(r, name)
+      end
+      object_server
+    end
+
+    # @api private
+    # Wait for a message to arrive. Return it once it is available.
+    def wait_for_message
+      @message_queue.pop # FIXME: EOFError
+    end
+
+    # @api private
+    # Send a message _msg_ on to the bus. This is done synchronously, thus
+    # the call will block until a reply message arrives.
+    # @param msg [Message]
+    # @param retc [Proc] the reply handler
+    # @yieldparam rmsg [MethodReturnMessage] the reply
+    # @yieldreturn [Array<Object>] the reply (out) parameters
+    def send_sync(msg, &retc) # :yields: reply/return message
+      return if msg.nil? # check if somethings wrong
+
+      @message_queue.push(msg)
+      @method_call_msgs[msg.serial] = msg
+      @method_call_replies[msg.serial] = retc
+
+      retm = wait_for_message
+      return if retm.nil? # check if somethings wrong
+
+      process(retm)
+      while @method_call_replies.key? msg.serial
+        retm = wait_for_message
+        process(retm)
+      end
+    rescue EOFError
+      new_err = DBus::Error.new("Connection dropped after we sent #{msg.inspect}")
+      raise new_err
+    end
+
+    # @api private
+    # Specify a code block that has to be executed when a reply for
+    # message _msg_ is received.
+    # @param msg [Message]
+    def on_return(msg, &retc)
+      # Have a better exception here
+      if msg.message_type != Message::METHOD_CALL
+        raise "on_return should only get method_calls"
+      end
+
+      @method_call_msgs[msg.serial] = msg
+      @method_call_replies[msg.serial] = retc
+    end
+
+    # Asks bus to send us messages matching mr, and execute slot when
+    # received
+    # @param match_rule [MatchRule,#to_s]
+    # @return [void] actually return whether the rule existed, internal detail
+    def add_match(match_rule, &slot)
+      # check this is a signal.
+      mrs = match_rule.to_s
+      DBus.logger.debug "#{@signal_matchrules.size} rules, adding #{mrs.inspect}"
+      rule_existed = @signal_matchrules.key?(mrs)
+      @signal_matchrules[mrs] = slot
+      rule_existed
+    end
+
+    # @param match_rule [MatchRule,#to_s]
+    # @return [void] actually return whether the rule existed, internal detail
+    def remove_match(match_rule)
+      mrs = match_rule.to_s
+      @signal_matchrules.delete(mrs).nil?
+    end
+
+    # @api private
+    # Process a message _msg_ based on its type.
+    # @param msg [Message]
+    def process(msg)
+      return if msg.nil? # check if somethings wrong
+
+      case msg.message_type
+      when Message::ERROR, Message::METHOD_RETURN
+        raise InvalidPacketException if msg.reply_serial.nil?
+
+        mcs = @method_call_replies[msg.reply_serial]
+        if !mcs
+          DBus.logger.debug "no return code for mcs: #{mcs.inspect} msg: #{msg.inspect}"
+        else
+          if msg.message_type == Message::ERROR
+            mcs.call(Error.new(msg))
+          else
+            mcs.call(msg)
+          end
+          @method_call_replies.delete(msg.reply_serial)
+          @method_call_msgs.delete(msg.reply_serial)
+        end
+      when DBus::Message::METHOD_CALL
+        if msg.path == "/org/freedesktop/DBus"
+          DBus.logger.debug "Got method call on /org/freedesktop/DBus"
+        end
+        node = object_server.get_node(msg.path, create: false)
+        # introspect a known path even if there is no object on it
+        if node &&
+           msg.interface == "org.freedesktop.DBus.Introspectable" &&
+           msg.member == "Introspect"
+          reply = Message.new(Message::METHOD_RETURN).reply_to(msg)
+          reply.sender = @unique_name
+          xml = node.to_xml(msg.path)
+          reply.add_param(Type::STRING, xml)
+          @message_queue.push(reply)
+        # dispatch for an object
+        elsif node&.object
+          node.object.dispatch(msg)
+        else
+          reply = Message.error(msg, "org.freedesktop.DBus.Error.UnknownObject",
+                                "Object #{msg.path} doesn't exist")
+          @message_queue.push(reply)
+        end
+      when DBus::Message::SIGNAL
+        # the signal can match multiple different rules
+        # clone to allow new signale handlers to be registered
+        @signal_matchrules.dup.each do |mrs, slot|
+          if DBus::MatchRule.new.from_s(mrs).match(msg)
+            slot.call(msg)
+          end
+        end
+      else
+        # spec(Message Format): Unknown types must be ignored.
+        DBus.logger.debug "Unknown message type: #{msg.message_type}"
+      end
+    rescue Exception => e
+      raise msg.annotate_exception(e)
+    end
+
+    # @api private
+    # Emit a signal event for the given _service_, object _obj_, interface
+    # _intf_ and signal _sig_ with arguments _args_.
+    # @param _service unused
+    # @param obj [DBus::Object]
+    # @param intf [Interface]
+    # @param sig [Signal]
+    # @param args arguments for the signal
+    def emit(_service, obj, intf, sig, *args)
+      m = Message.new(DBus::Message::SIGNAL)
+      m.path = obj.path
+      m.interface = intf.name
+      m.member = sig.name
+      i = 0
+      sig.params.each do |par|
+        m.add_param(par.type, args[i])
+        i += 1
+      end
+      @message_queue.push(m)
+    end
+  end
+
+  # A {Connection} that is talking directly to a peer, with no bus daemon in between.
+  # A prominent example is the PulseAudio connection,
+  # see https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/Clients/DBus/
+  # When starting, it still starts with authentication but omits the Hello message.
+  class PeerConnection < Connection
+    # Get a {ProxyPeerService}, a dummy helper to get {ProxyObject}s for
+    # a {PeerConnection}.
+    # @return [ProxyPeerService]
+    def peer_service
+      ProxyPeerService.new(self)
+    end
+  end
+end

data/lib/dbus/object.rb

@@ -19,31 +19,37 @@ module DBus
   # Objects that are going to be exported by a D-Bus service
   # should inherit from this class. At the client side, use {ProxyObject}.
   class Object
-    # The path of the object.
+    # @return [ObjectPath] The path of the object.
     attr_reader :path
 
     # The interfaces that the object supports. Hash: String => Interface
     my_class_attribute :intfs
     self.intfs = {}
 
-    # @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 ObjectServer#export to export it.
+    # @param path [ObjectPath] The path of the object.
     def initialize(path)
       @path = path
-      @connection = nil
+      # TODO: what parts of our API are supposed to work before we're exported?
+      self.object_server = nil
+    end
+
+    # @return [ObjectServer] the server the object is exported by
+    def object_server
+      # tests may mock the old ivar
+      @object_server || @service
     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
+    # @param server [ObjectServer] the server the object is exported by
+    # @note only the server itself should call this in its #export/#unexport
+    def object_server=(server)
+      # until v0.22.1 there was attr_writer :service
+      # so subclasses only could use @service
+      @object_server = @service = server
     end
 
     # Dispatch a message _msg_ to call exported methods
@@ -78,7 +84,9 @@ module DBus
           dbus_msg_exc = msg.annotate_exception(e)
           reply = ErrorMessage.from_exception(dbus_msg_exc).reply_to(msg)
         end
-        @connection.message_queue.push(reply)
+        # TODO: this method chain is too long,
+        # we should probably just return reply [Message] like we get a [Message]
+        object_server.connection.message_queue.push(reply)
       end
     end
 
@@ -316,7 +324,9 @@ module DBus
     # @param sig [Signal]
     # @param args arguments for the signal
     def emit(intf, sig, *args)
-      @connection.emit(nil, self, intf, sig, *args)
+      raise "Cannot emit signal #{intf.name}.#{sig.name} before #{path} is exported" if object_server.nil?
+
+      object_server.connection.emit(nil, self, intf, sig, *args)
     end
 
     # Defines a signal for the object with a given name _sym_ and _prototype_.

data/lib/dbus/object_manager.rb

@@ -20,27 +20,31 @@ module DBus
   module ObjectManager
     OBJECT_MANAGER_INTERFACE = "org.freedesktop.DBus.ObjectManager"
 
+    # Implements `the GetManagedObjects` method.
     # @return [Hash{ObjectPath => Hash{String => Hash{String => Data::Base}}}]
     #   object -> interface -> property -> value
     def managed_objects
-      descendant_objects = connection.object_server.descendants_for(path)
+      descendant_objects = object_server.descendants_for(path)
       descendant_objects.each_with_object({}) do |obj, hash|
         hash[obj.path] = obj.interfaces_and_properties
       end
     end
 
+    # {ObjectServer#export} will call this for you to emit the `InterfacesAdded` signal.
     # @param object [DBus::Object]
     # @return [void]
     def object_added(object)
       InterfacesAdded(object.path, object.interfaces_and_properties)
     end
 
+    # {ObjectServer#unexport} will call this for you to emit the `InterfacesRemoved` signal.
     # @param object [DBus::Object]
     # @return [void]
     def object_removed(object)
       InterfacesRemoved(object.path, object.intfs.keys)
     end
 
+    # Module#included, a hook for `include ObjectManager`, declares its dbus_interface.
     def self.included(base)
       base.class_eval do
         dbus_interface OBJECT_MANAGER_INTERFACE do

data/lib/dbus/object_server.rb

@@ -36,7 +36,7 @@ module DBus
 
     # Retrieves an object at the given _path_
     # @param path [ObjectPath]
-    # @return [DBus::Object]
+    # @return [DBus::Object,nil]
     def object(path)
       node = get_node(path, create: false)
       node&.object
@@ -45,34 +45,48 @@ module DBus
 
     # 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)
-      # 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
+      raise "At #{obj.path} there is already an object #{node.object.inspect}" if node.object
 
       node.object = obj
 
-      obj.connection = @connection
+      obj.object_server = self
       object_manager_for(obj)&.object_added(obj)
     end
 
-    # Undo exporting an object _obj_.
+    # 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 [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]
+    # @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.connection = nil
-      parent_node.delete(node_name).object
+      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*
@@ -98,6 +112,22 @@ module DBus
       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

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_service.rb

@@ -22,11 +22,12 @@ module DBus
   #   p manager.ListImages
   class ProxyService < NodeTree
     # @return [BusName,nil] The service name.
-    # May be nil for peer connections
+    # 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
@@ -76,7 +77,7 @@ module DBus
     # Perform a recursive retrospection on the given current _node_
     # on the given _path_.
     def rec_introspect(node, path)
-      xml = bus.introspect_data(@name, path)
+      xml = connection.introspect_data(@name, path)
       intfs, subnodes = IntrospectXMLParser.new(xml).parse
       subnodes.each do |nodename|
         subnode = node[nodename] = Node.new(nodename)
@@ -92,4 +93,15 @@ module DBus
       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

@@ -26,6 +26,7 @@ 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"