zbus-lockstep

Keep type definitions in lockstep with DBus XML descriptions, with zbus.

This provides means to match the signature of <T as zvariant::Type>::signature() with a corresponding signature from a DBus XML file.

zbus-lockstep prevents definitions from drifting apart by offering means to retrieve and assert that the signature of a type corresponds to signature in the currently valid XML.

Why

To ensure that a type's implementation matches a signature in an external XML DBus description.

In the context of IPC over DBus - especially where are multiple implementations of servers and/or clients - it is necessary for each implementation to match what others expect. The XML descriptions may act as a shared overarching frame of reference or "single source of all truth". Having a single point of reference helps all implementers meet expectations on protocol conformance.

How

Add zbus-lockstep to Cargo.toml's dev-dependencies:

[dev-dependencies]
zbus-lockstep = "0.1.0"

Consider the followwing XML description, an interface with a single, simple signal in the Cache.xml file:

<node>
  <interface name="org.example.Node">

    <signal name="RemoveNode">
      <arg name="nodeRemoved" type="(so)"/>
    </signal>

  </interface>
</node>

The type in our implementation might look like this:

#[derive(Type)]
struct Node {
    name: String,
    path: OwnedObjectPath,
}

The derive macro in this example implements the zvariant::Type. This means we can now call <Node as Type::signature(), which will return a zvariant::Signature of the type.

The test below shows how zbus-lockstep may be used given what we know about the type.

    use zbus_lockstep;

    #[test]
    fn test_get_signature_of_cache_remove_accessible() {
        let xml = PathBuf::from("xml/Node.xml");
        let iface = "org.example.Node";
        let member = "RemoveNode";

        let signature = get_signal_body_type(xml, iface, member, None).unwrap();
        assert_eq!(signature, Node::signature());
    }

Obviously, the user here needs to take care to ensure that the XML descriptions that are in use, are indeed currently valid and the most recent available.

To-do

• Provide proc-macro to derive a validation

#[derive(Type)] 
#[validate(signal = "Activate", path = "../xml/introspected.xml")]
pub struct ActivateEvent {
    event: String,
    serial: u32,
    // 
}

Caveat: Requires a sub-crate.

Acknowledgement

This crate started out as a fork from Tait Hoyem's zbus-xml-match.

LICENSE

MIT