dbus-native

The E2E testing environment uses a node:24-bookworm container to simulate a Linux desktop environment. It provides both a system bus and a session bus.

Available Services

Available Clients for Interop Testing

• gdbus (GLib)
• busctl (systemd/sd-bus)
• python3-dbus
• dbus-send
• dbus-monitor

Limitations

• systemd/logind/hostnamed: These require PID 1 and are not available in the standard container.
• UNIX_FD: Passing file descriptors is not supported on Node.js (though it is supported in the Bun implementation).
• Real Hardware: Services like UPower and UDisks2 run without hardware, so device trees will be shallow.

D-Bus allows passing file descriptors using the UNIX_FD type. In a message, the body contains a uint32 index (h) pointing to the array of descriptors provided in msg.fds.

Platform Support

• Bun: Works out of the box using bun:ffi. A connection under Bun automatically supports passing FDs (bus.connection.canPassFds will be true).
• Node.js: Does not support passing file descriptors. Messages attempting to carry them will be refused with an error.

Implementation Details

• Ordering: Descriptors must arrive in order and must not arrive after the message bytes.
• Batching: Messages carrying file descriptors are never batched; they flush the cork and travel individually.
• Ownership: Received descriptors are live FDs in your process; you are responsible for closing them. Descriptors you send stay yours, but Bun's transport dups them, so you can close your copy immediately after the call returns.

Custom Transports

You can provide a custom transport via opts.stream. The transport must implement:

• writeWithFds(bytes, fds): To send descriptors.
• emit('fds', fds): To receive descriptors.
• closeFds(fds) (optional): To close unclaimed descriptors.

Sending an FD:

// Sending
bus.connection.message({
  destination: 'org.example.Sink',
  path: '/org/example/Sink',
  interface: 'org.example.Sink',
  member: 'Take',
  signature: 'sh',
  body: ['a name', 0], // 0 is the index into fds
  fds: [fd]
});

// Receiving
bus.connection.on('message', msg => {
  if (msg.fds) console.log(msg.fds[msg.body[1]]);
});

Properties in dbus-native default to readwrite. You can explicitly set access to read or write.

Property Access Enforcement

Emitting Property Changes

When using exportInterface (the positional form), Properties.Set automatically emits org.freedesktop.DBus.Properties.PropertiesChanged.

If you are manually updating an implementation object, you must notify the bus yourself: bus.emitPropertiesChanged(path, iface.name, { PropertyName: newValue });

To notify that a property has been invalidated (e.g., a write-only property or an expensive computation), use the invalidated argument: bus.emitPropertiesChanged(path, iface.name, {}, ['ExpensiveProperty']);

The library provides configuration options to control how D-Bus messages are unmarshalled into JavaScript.

plainValues (Boolean)

Controls the shape of dictionaries and variants.

• true (default): Variants read as the raw value; dicts read as plain objects.
• false: Variants read as [signatureTree, [value]]; dicts read as arrays of pairs.

variants (String: 'plain' | 'tree' | 'wrap')

Controls how a variant (v) is returned, independent of the dict shape.

• 'plain' (default): Returns the raw value. The signature is discarded.
• 'tree': Returns [signatureTree, [value]]. Useful for inspection.
• 'wrap': Returns a Variant object. This is the recommended shape for routers or services that need to inspect and then forward values, as the Variant can be written back to the bus without losing its original type information.

// Example: Using 'wrap' to preserve type information for inspection/forwarding
const bus = dbus.sessionBus({ variants: 'wrap' });

const props = await iface.$readProp('Metadata');
// props.Volume is a Variant object
console.log(props.Volume.signature); // e.g., 'd'
console.log(props.Volume.value);     // e.g., 0.5

// You can pass this directly back to another service
await sink.SetOptions(props);

All asynchronous methods in dbus-native support both Node-style callbacks and Promises (thenables).

Callbacks

Pass a (err, result) callback as the last argument.

Promises (Thenables)

Omit the callback to receive a thenable. Note that the returned object is a thenable, not a Promise (instanceof Promise is false). This is a deliberate design to allow "fire-and-forget" calls; the underlying promise is only constructed lazily when you observe the outcome (e.g., via await or .then()). If you ignore the return value, no promise is constructed, preventing unhandled rejections.

Resolution Logic

Resolution depends on the number of values in the D-Bus reply body:

• No values: Resolves to undefined.
• One value: Resolves to the value.
• Two or more values: Resolves to an array of values.

Rejections always return a DBusError containing stack frames from where the call was made.

// Using a callback
bus.getId((err, id) => {
  if (err) throw err;
  console.log(id);
});

// Using await (Promise-style)
const id = await bus.getId();

The library supports the D-Bus UNIX_FD (h) type, allowing the passing of arbitrary file descriptors (files, pipes, etc.) between processes.

Current Support Status:

• Bun: Full support is available via a built-in transport (lib/transport-bun.js) that uses bun:ffi to call sendmsg/recvmsg directly. This allows passing descriptors without external dependencies.
• Node.js: Built-in support is currently unavailable because the Node.js net module does not expose an API for passing ancillary data (file descriptors) on Unix sockets.

How to use it (Custom Transports): If you provide a custom transport that implements the necessary seam (stream.writeWithFds(bytes, fds) and an 'fds' event), you can use UNIX_FD even in Node.js.

Key API properties for FD negotiation:

• connection.canPassFds: Reports if the local side can pass descriptors.
• connection.unixFdsAgreed: Reports if the peer has agreed to the NEGOTIATE_UNIX_FD protocol.
• Messages containing FDs are never batched; ancillary data is attached to specific writes.