dbus

dbus is a pure-Go implementation of the D-Bus wire protocol, giving Go programs a way to call methods, emit and receive signals, and export objects on the session or system bus without linking against libdbus via CGo. It implements the full D-Bus message format itself — authentication, marshaling of the D-Bus type system, and transport over Unix sockets or TCP — and exposes it through an idiomatic, goroutine-safe Go API built on channels.

The library is widely used as the D-Bus layer underneath higher-level Go projects, including desktop and Bluetooth tooling, systemd bindings, and desktop-notification helpers, which speaks to its stability as low-level plumbing even though its own API is explicitly documented as unstable and subject to change.

What You Get

• A complete native implementation of the D-Bus message protocol, including authentication (EXTERNAL, DBUS_COOKIE_SHA1) and wire-level marshaling of the D-Bus type system
• A goroutine-safe Conn type with channel-based APIs for asynchronous method calls and signal delivery
• An Export mechanism that uses reflection to turn a plain Go value’s methods into D-Bus object methods automatically
• Subpackages introspect and prop for implementing the standard D-Bus introspection and property-change interfaces
• Cross-platform transport support (Unix sockets, TCP, and platform-specific credential passing) selected via Go build tags for Linux, Darwin, Windows, and BSD variants
• Support for passing Unix file descriptors over the bus when the underlying transport allows it

Common Use Cases

• Talking to system services over the D-Bus system bus, such as NetworkManager, systemd, or UPower, from a Go daemon or CLI tool
• Sending desktop notifications or reading media-key and Bluetooth events on Linux desktops from a Go application
• Implementing a Go service that exposes its own D-Bus object and interface for other processes to call and introspect
• Building cross-platform Go libraries (like Bluetooth or desktop-integration packages) that need a dependency-free D-Bus client on Linux without requiring CGo

Under The Hood

Architecture The library is organized around a Conn type (conn.go) that embeds a transport and coordinates authentication, message dispatch, and signal delivery through a handler, signalHandler, serialGen, and pluggable interceptors. Outgoing and incoming D-Bus messages are represented by the protocol types in message.go and encoded/decoded via encoder.go/decoder.go against the D-Bus type system defined in sig.go. Authentication is abstracted behind an Auth interface (auth.go) so mechanisms like EXTERNAL and DBUS_COOKIE_SHA1 can be swapped or extended. Server-side object exposure goes through export.go and object.go, which use reflection to translate a Go value’s methods into callable D-Bus methods, while the introspect and prop subpackages layer the standard introspection and property-change interfaces on top. This separation means the core protocol, transport, and object-export layers can evolve independently, though the primary shared abstraction other packages build on is the Conn itself.

Tech Stack The module targets Go 1.20+ and declares a single external dependency, golang.org/x/sys, used for low-level platform syscalls needed by the transport layer. There is no web, ORM, or CLI framework involved — this is a system-level protocol library, not an application framework. Cross-platform support is handled through Go build tags rather than runtime branching: transport and authentication files are suffixed _unix, _tcp, _darwin, _windows, and per-BSD-variant files handle credential passing, so each OS gets its own compiled-in implementation of socket connection and peer-credential retrieval. CI runs a lint job (golangci-lint) plus a test matrix across Go 1.20 through 1.23 on Linux.

Code Quality The repository ships an extensive set of test files alongside nearly every source file, including a dedicated fuzz test for the wire-protocol decoder, indicating deliberate attention to malformed-input handling. Error handling is explicit and typed: the library defines a dedicated Error type carrying a D-Bus error name and argument list, plus sentinel errors like ErrClosed, rather than swallowing failures. Naming follows idiomatic Go conventions (exported CamelCase types and functions, unexported internal helpers), and golangci-lint runs in CI on every push and pull request against the default branch, giving the codebase consistent static-analysis coverage.

What Makes It Unique The library’s main technical distinction is implementing the D-Bus wire protocol natively in Go rather than wrapping the C libdbus reference implementation via CGo, which removes a native build dependency and keeps cross-compilation simple — a meaningful advantage for Go tooling that needs to talk to D-Bus. Its reflection-based Export mechanism, which turns a plain Go value into a fully addressable D-Bus object automatically, together with a channel-based API for async calls and signals, gives it an idiomatic feel that other Go D-Bus wrappers built on CGo bindings generally lack. The authors are explicit that the public API is still considered unstable, favoring correctness and flexibility over API stability guarantees at this stage.