# mdbus Monstar DBUS - A small D-Bus client transport for Zig. `mdbus` speaks enough of the D-Bus protocol to talk to services on the session bus: it authenticates over a Unix-domain socket, encodes and decodes the wire format, sends method calls and signals, correlates replies with their calls, and passes Unix file descriptors. It is deliberately *not* a general D-Bus binding — there is no object model, no introspection, and no code generation. Service-specific message construction belongs in the module that owns it. This library was originally part of [Monstar](https://github.com/rockorager/monstar). The API reference is generated from the module's doc comments and published at ****. ## Requirements - Zig 0.17 - Linux - A session bus reachable over a Unix socket (`DBUS_SESSION_BUS_ADDRESS`, or `$XDG_RUNTIME_DIR/bus` as a fallback) ## Where this lives The canonical repository is on my Forgejo instance, and Codeberg and [Tangled](https://tangled.org/jcollie.dev/mdbus) carry mirrors of it: ``` sh git clone https://git.jcollie.dev/jeff/mdbus.git git clone https://codeberg.org/jcollie/mdbus.git git clone https://tangled.org/jcollie.dev/mdbus ``` It is also on [Radicle](https://radicle.xyz/) as `rad:z3EbByAjuCYv287zy8crpoXiaXszv`, which is the only name that finds it there — a peer-to-peer repository has no host to browse: ``` sh rad clone rad:z3EbByAjuCYv287zy8crpoXiaXszv ``` All four serve the same history. CI, the published documentation and the issue tracker follow the canonical one. ## Installation Add the dependency to your `build.zig.zon`: ``` sh zig fetch --save https://git.jcollie.dev/jeff/mdbus/archive/main.tar.gz ``` `main` targets Zig 0.17. Zig 0.16 is served by the `zig-0.16` branch, which starts at the `v0.1.0` tag and takes only critical fixes: ``` sh zig fetch --save https://git.jcollie.dev/jeff/mdbus/archive/zig-0.16.tar.gz ``` Then wire the module into your `build.zig`: ``` zig const mdbus = b.dependency("mdbus", .{ .target = target, .optimize = optimize, }); exe.root_module.addImport("mdbus", mdbus.module("mdbus")); ``` ### Message size limit `mdbus` refuses to encode or accept a message larger than 16 MiB by default. The limit is what bounds how much a hostile peer can make the library allocate, so it is deliberately well under the 128 MiB the protocol permits. A build that expects larger messages — or that wants a tighter bound than the default — sets `max_message_size`: ``` zig const mdbus = b.dependency("mdbus", .{ .target = target, .optimize = optimize, .max_message_size = @as(usize, 64 * 1024 * 1024), }); ``` A value above the protocol maximum, or below a message's 16-byte fixed header, fails the build rather than being clamped silently. The value in effect is readable as `mdbus.max_message_size`, and the protocol's own ceiling as `mdbus.spec_max_message_size`. Raise it only as far as the messages actually expected: a connection queues up to 256 messages, so the worst-case memory a peer can pin scales with this setting. ## Usage ``` zig const std = @import("std"); const mdbus = @import("mdbus"); pub fn listNames( io: std.Io, allocator: std.mem.Allocator, environ: std.process.Environ, ) !void { var connection = try mdbus.Connection.connectSession(io, allocator, environ); defer connection.deinit(); var reply = try connection.call(.{ .destination = "org.freedesktop.DBus", .path = "/org/freedesktop/DBus", .interface = "org.freedesktop.DBus", .member = "ListNames", }, "", &.{}, &.{}, 5000); defer reply.deinit(); if (reply.messageType() == .error_reply) return error.RemoteError; var decoder = reply.bodyDecoder(); const end = try decoder.beginArray('s'); while (!try decoder.arrayFinished(end)) { const name = try decoder.string(); std.debug.print("{s}\n", .{name}); } try decoder.endArray(end); } ``` Arguments are built with an `Encoder` and passed alongside their D-Bus signature. To send a file descriptor, encode its index into the `fds` slice: ``` zig var body: mdbus.Connection.Encoder = .init(allocator); defer body.deinit(); try body.unixFd(0); var reply = try connection.call(.{ .destination = "com.example.Service", .path = "/com/example/Service", .interface = "com.example.Service", .member = "TakeFd", }, "h", body.bytes(), &.{fd}, 1000); defer reply.deinit(); ``` Complete programs live under [examples](examples), each its own package consuming `mdbus` as a path dependency the way an out-of-tree caller would: [open-uri](examples/open-uri) opens a URL through the desktop portal and waits for the portal's `Response` signal, [open-file](examples/open-file) does the same for a local file, which the portal takes as a passed file descriptor rather than a path, and [open-directory](examples/open-directory) reveals a file in the file manager the same way. From an example's directory: ``` sh zig build run -- https://example.org ``` ## Encoding a body A body is built value by value with an `Encoder`, then handed to `call`, `sendSignal`, or `sendReply` together with the signature describing it. The encoder does not track the signature — you state it once, at the send, and write values that match it. What the encoder does track is alignment: every value is padded to the boundary its type requires, computed against the message as a whole, which is the part of the wire format worth outsourcing. Scalars and strings are single calls, written in signature order. This body matches the signature `sub`: ``` zig var body: mdbus.Connection.Encoder = .init(allocator); defer body.deinit(); try body.string("backlight"); try body.uint32(40); try body.boolean(true); ``` An array is bracketed by `beginArray` and `endArray`. The wire format prefixes an array with its byte length, which is not known until the elements have been written, so `beginArray` leaves a hole and returns a bookmark, and `endArray` patches the length in. `beginArray` takes the character the element type's signature begins with — `'i'` for `ai`, `'('` for `a(us)`, `'{'` for `a{sv}` — and derives the element alignment from it. A struct's fields are preceded by `structAlignment`, which pads to the eight-byte boundary every struct starts on. Together, for `a(us)`: ``` zig const entries = try body.beginArray('('); for (devices) |device| { try body.structAlignment(); try body.uint32(device.id); try body.string(device.name); } try body.endArray(entries); ``` A dictionary is an array of dict entries, and an entry is a key, a value, and the same eight-byte alignment a struct gets — `dictEntryAlignment`, named for what it precedes. The common `a{sv}` pairs string keys with variants, where a variant is a signature naming exactly one type followed by a value of that type: ``` zig const properties = try body.beginArray('{'); try body.dictEntryAlignment(); try body.string("Volume"); try body.variantSignature("d"); try body.double(0.5); try body.dictEntryAlignment(); try body.string("Muted"); try body.variantSignature("b"); try body.boolean(false); try body.endArray(properties); ``` The content of a byte array moves in bulk rather than a call per byte, so `ay` carrying real data is three calls regardless of its size: ``` zig const blob = try body.beginArray('y'); try body.byteSlice(image_data); try body.endArray(blob); ``` Sending is where the signature is stated and checked — the encoder trusts you until then, and the values written must match it: ``` zig var reply = try connection.call(.{ .destination = "com.example.Mixer", .path = "/com/example/Mixer", .interface = "com.example.Mixer", .member = "Configure", }, "suba(us)a{sv}ay", body.bytes(), &.{}, 5000); defer reply.deinit(); ``` The connection sends a body as a gathered write: the header and your body bytes go to the socket as two vectors of one `sendmsg`, so a large body — a megabyte of `ay`, say — is handed to the kernel directly rather than copied into a full-message buffer first. ### Reusing encoding memory The allocator handed to `Encoder.init` is where the body's bytes accumulate, and the encoder does not care where that memory comes from. A caller assembling many messages can hand it a `std.heap.FixedBufferAllocator` over one long-lived buffer, or an `ArenaAllocator` it resets between messages, which turns per-message heap traffic into reuse of the same warm memory — worth doing when profiling shows allocation churn, and not before. ``` zig var arena = std.heap.ArenaAllocator.init(allocator); defer arena.deinit(); for (readings) |reading| { // Reclaims every body at once and keeps the buffer for the next one, // which is also why no encoder deinit is needed here. _ = arena.reset(.retain_capacity); var body: mdbus.Connection.Encoder = .init(arena.allocator()); try body.string(reading.name); try body.double(reading.value); try connection.sendSignal(.{ .path = "/com/example/Sensor", .interface = "com.example.Sensor", .member = "Reading", }, "sd", body.bytes()); } ``` The allocator given to `connectSession` is a different matter: the connection allocates every *received* message from it, and each lives until its `deinit`, so that one must be a real allocator that can free independently — never an arena being reset while messages are alive. ## Decoding a body Reading mirrors writing: `Message.bodyDecoder` returns a `Decoder` positioned at the start of the body, and values are read in the order the signature (`Message.bodySignature`) lists them. A message that came out of `parseMessage` — which is every message a `Connection` hands you — has already had its body validated against its signature, so decoding follows the signature without running off the end. Strings, paths, and byte slices alias the message's buffer rather than being copied, and are valid until the message's `deinit`. An array read is bracketed the way an array write is: `beginArray` takes the same element character, returns the position where the array ends, and `arrayFinished` against that position drives the element loop. For the `a(us)` written above: ``` zig var decoder = reply.bodyDecoder(); const entries = try decoder.beginArray('('); while (!try decoder.arrayFinished(entries)) { try decoder.structAlignment(); const id = try decoder.uint32(); const name = try decoder.string(); std.debug.print("{d}: {s}\n", .{ id, name }); } try decoder.endArray(entries); ``` A dictionary reads as an array of eight-aligned entries — `structAlignment` covers a dict entry too, since both pad to the same boundary. A variant's value is read according to the signature that opens it, and `skipSignatureValue` steps over a value of any type, which is what to do with a key you do not recognize: ``` zig const properties = try decoder.beginArray('{'); while (!try decoder.arrayFinished(properties)) { try decoder.structAlignment(); const key = try decoder.string(); const signature = try decoder.variantSignature(); if (std.mem.eql(u8, key, "Volume") and std.mem.eql(u8, signature, "d")) { volume = try decoder.double(); } else { try decoder.skipSignatureValue(signature); } } try decoder.endArray(properties); ``` A byte array comes back in bulk as a slice of the message, with the array's end position saying how much to take: ``` zig const blob = try decoder.beginArray('y'); const image_data = try decoder.byteSlice(blob); try decoder.endArray(blob); ``` A received file descriptor travels as an `h` index into the message's descriptor array, which is resolved — after checking it, since indices are values a peer chose — against `Message.fds`: ``` zig const index = try decoder.unixFd(); if (index >= reply.fds.len) return error.InvalidMessage; const fd = reply.fds[index]; ``` Finishing with `decoder.end()` asserts the body held nothing beyond what was read, which catches a signature misunderstanding on the last value as surely as on the first. ## API The full API reference, rendered from the module's doc comments, is published at . `Connection` is the entry point: | Function | Purpose | | ----------------------------- | -------------------------------------------------------- | | `connectSession` | Connect, authenticate, and say `Hello` to the bus | | `connectSystem` | The same, to the system bus | | `connectAddress` | The same, to a bus at a D-Bus server address | | `call` | Send a method call and wait for its reply | | `sendMethod` | Send a method call, returning its serial | | `sendSignal` | Emit a signal, broadcast or to one destination | | `sendReply` | Answer a received method call with its return value | | `sendError` | Answer a received method call with an error | | `addMatch` | Install a match rule and confirm the bus accepted it | | `waitForReply` | Wait for one serial, queueing unrelated messages | | `waitForMessage` | Wait for the first message a predicate accepts | | `takeMessage` | Take the first message a predicate accepts, non-blocking | | `nextMessage` | Take the next queued or received message, non-blocking | | `uniqueName` | The unique name the bus assigned in reply to `Hello` | | `getFd` / `hasQueuedMessages` | Integrate the connection into an event loop | A received method call carries the unique name of whoever sent it, which is what `sendReply` and `sendError` address their answer to, so answering one takes nothing beyond the message itself. `Message.noReplyExpected` reports whether the caller is waiting for that answer at all. Messages own their memory and their received descriptors; call `deinit` on every message you are handed. `Message.bodyDecoder` returns a bounds-checked `Decoder` over the body, and `Encoder` builds bodies for outgoing messages. Both handle every type in the specification: bytes, booleans, signed and unsigned 16-, 32-, and 64-bit integers, doubles, Unix file descriptors, strings, object paths, and signatures, plus arrays, structs, dict entries, and variants. The content of a byte array moves in bulk through `Encoder.byteSlice` and `Decoder.byteSlice`, and an `i` array's through `int32Slice`, rather than a call per element. Neither tracks a signature of its own — the caller states the signature and writes values that match it — but `Decoder.skipSignatureValue` walks any value from its signature, and `parseMessage` uses it to validate an incoming body before returning it. Because dispatch is non-blocking and driven by `getFd`, an application can poll the connection alongside its other file descriptors and drain messages with `nextMessage` as they arrive. `takeMessage` and `waitForMessage` take a context value and a comptime predicate, `fn (@TypeOf(context), *const Message) bool`, and remove only the first message it accepts; everything else stays queued, in arrival order, for `nextMessage`. That lets a library wait for its own reply or signal on a connection the application shares without swallowing messages the application is expecting: ``` zig fn isFrom(sender: []const u8, message: *const mdbus.Connection.Message) bool { return std.mem.eql(u8, message.header.sender orelse "", sender); } var signal = try connection.waitForMessage(@as([]const u8, ":1.42"), isFrom, 5000); defer signal.deinit(); ``` ## Development A Nix flake provides Zig 0.17 and the REUSE tooling: ``` sh nix develop zig build test ``` The unit tests run without a bus. The live-bus tests in `src/live_bus_test.zig` skip themselves unless a session bus is available and `MONSTAR_DBUS_INTEGRATION=1` is set: ``` sh MONSTAR_DBUS_INTEGRATION=1 zig build test ``` To run the whole suite against a bus that is known to be dbus-broker, without needing one on the development machine, the flake boots a NixOS virtual machine whose session bus is dbus-broker and runs the tests inside it: ``` sh nix build .#checks.x86_64-linux.dbus-broker ``` The check fails unless every test *ran*, so a live-bus test that skipped itself is treated as a failure rather than a pass. `packages..test-runner` builds the same test binary on its own, which is what the virtual machine installs and executes. CI runs that check too, as `nix flake check` in a job of its own, on a runner able to boot the guest. The live-bus tests are therefore covered on every push rather than only when somebody remembers to run them by hand. `zig build docs` renders the module's doc comments to `zig-out/docs`, and `zig build docs-serve` builds the same pages and serves them at , with `-Ddocs-port=N` to choose another port. A server is needed rather than opening the files directly, because the viewer fetches its data at runtime and a browser refuses that from a `file://` page; `zig std` works this way for the same reason. CI publishes the same pages to on every push to `main` that passes the tests. Licensing headers follow the [REUSE](https://reuse.software/) specification; `reuse lint` checks them. ## License MIT. See [LICENSES/MIT.txt](LICENSES/MIT.txt). The D-Bus client originated in Tim Culverhouse's Monstar project and is reused here under the same license; Tim is credited as the original author in every file header. ## References cited Kept in the `mdbus` Zotero collection. - Pennington, Havoc, Anders Carlsson, Alexander Larsson, Sven Herzberg, Simon McVittie, and David Zeuthen. *D-Bus Specification*. freedesktop.org. . The wire format `src/wire` encodes and decodes, its limits, the message types, and the authentication protocol `Connection.zig` speaks. - Melnikov, A., ed., and K. Zeilenga, ed. *Simple Authentication and Security Layer (SASL)*. RFC 4422. Internet Engineering Task Force (IETF), June 2006. . Appendix A's `EXTERNAL` mechanism, which is how a client proves who it is to a bus: by the credentials of the Unix socket it connected over.