crystal-dbus-native

Native, zero-dependency D-Bus wire protocol for Crystal featuring BodyCodec marshaling, SASL EXTERNAL authentication, and SCM_RIGHTS UNIX file descriptor passing.

GitLab Project Metadata:

• Description: Native, zero-dependency D-Bus wire protocol for Crystal featuring BodyCodec marshaling, SASL EXTERNAL authentication, and SCM_RIGHTS UNIX file descriptor passing.
• Topics/Tags: crystal, crystal-lang, dbus, ipc, linux, unix-sockets, scm-rights, zero-dependencies, security, gplv3

Overview

crystal-dbus-native provides a pure, zero-dependency Crystal implementation of the D-Bus wire protocol v1, general-purpose body marshaling (BodyCodec and Variant), SASL EXTERNAL authentication with NEGOTIATE_UNIX_FD negotiation, out-of-band UNIX domain socket file descriptor passing (SCM_RIGHTS), multiplexed fiber RPC routing (ReplyRouter), match-rule signal subscriptions, and typed PropertiesProxy/IntrospectableProxy client helpers.

Key Highlights

1. Zero C-Library Dependencies: Communicates directly with Linux system and session UNIX domain sockets without libdbus-1 or libsystemd FFI bindings.
2. Complete Body Marshaling (BodyCodec & Variant): Encodes and decodes all basic D-Bus types, nested structs (StructValue), dictionaries (a{sv}), Variant, ObjectPath, Signature, and UnixFD in both little-endian and big-endian formats with 1, 2, 4, and 8-byte alignment enforcement.
3. Secure SCM_RIGHTS File Descriptor Passing: Wraps sendmsg/recvmsg with MSG_CMSG_CLOEXEC and guarantees automatic descriptor cleanup on MSG_CTRUNC truncation or framing errors.
4. Multiplexed Fiber RPC & Signal Subscriptions: ReplyRouter demultiplexes out-of-order replies across concurrent fibers without head-of-line blocking and dispatches AddMatch signal subscriptions to bounded Channel(DBusMessage).new(64) channels.
5. Standard Interface Client Proxies: PropertiesProxy (get, set, get_all, decode_properties_changed) and IntrospectableProxy (introspect) provide strongly-typed access to standard freedesktop interfaces.

Installation

Add crystal-dbus-native to your application's shard.yml:

dependencies:
  crystal-dbus-native:
    gitlab: renich/crystal-dbus-native
    version: ~> 0.3.1

Then install the shard:

shards install

Usage

require "crystal-dbus-native"

# Connect to the session or system bus and perform SASL + Hello handshake
connection = Crystal::Dbus::Native::DBusConnection.open_session
unique_name = connection.start(negotiate_unix_fd: true)
puts "Connected to D-Bus (unique name: #{unique_name}, GUID: #{connection.server_guid})"

# Invoke a D-Bus method and decode its reply body
reply = connection.call(
  destination: "org.freedesktop.DBus",
  path: "/org/freedesktop/DBus",
  interface: "org.freedesktop.DBus",
  member: "GetId"
)
puts "Bus ID: #{reply.decode_body.first}"

# Inspect XML interfaces or read properties via typed client proxies
introspect = Crystal::Dbus::Native::IntrospectableProxy.new(
  connection,
  "org.freedesktop.DBus",
  "/org/freedesktop/DBus"
)
puts introspect.introspect

props = Crystal::Dbus::Native::PropertiesProxy.new(
  connection,
  "org.freedesktop.DBus",
  "/org/freedesktop/DBus"
)
features = props.get("org.freedesktop.DBus", "Features")
puts "Bus features signature: #{features.signature}"

# Subscribe to D-Bus signals via AddMatch
rule = "type='signal',interface='org.freedesktop.DBus',member='NameOwnerChanged'"
sig_ch = connection.subscribe_signal(rule)
connection.unsubscribe_signal(rule, sig_ch)

connection.close

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

| Target | Description | | :--- | :--- | | make all | Runs lint, doc-check, and test | | make test | Executes the spec test suite (crystal spec) | | make lint | Runs crystal tool format --check, Ameba (--all), and Flaw SAST scanner | | make doc-check | Lints all reStructuredText files using crstlint and rstcheck | | make check | Alias for all (lint, doc-check, and test) | | make format | Formats all Crystal source and spec files | | make docs | Generates Crystal API docs and Sphinx dirhtml documentation | | make deps | Installs Shards dependencies and builds bin/ameba and bin/flaw | | make clean | Removes build artifacts, generated docs, and caches |

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

| Guide | Scope & Highlights | Entry Point | | :--- | :--- | :--- | | Business Context & Strategy | Ecosystem problem statement, ROI metrics, and user personas. | Business Specs | | Functional Specifications | Requirements [FUNC-001]–[FUNC-007] and traceability matrix. | Functional Specs | | Technical Architecture | Specifications [TECH-001]–[TECH-007], D2 diagrams, and threat model. | Technical Specs | | Release Playbook | SemVer, Keep a Changelog, and GPG-signed GitLab release steps. | Release Procedure | | Architecture Decisions (ADRs) | Immutable logs of architectural decisions and trade-offs. | ADR Index | | Project Roadmap | Phased milestone tracking, task dependencies, and critical paths. | Project Roadmap | | User Guides | Installation, RPC usage, and error handling examples. | User Manual | | Crystal API Reference | Complete interactive type hierarchy and method signatures. | API Reference |

Contributing & Code of Honor

All contributions must adhere to the Universal Code of Honor and Contributing Guidelines.

License

• Software: GNU General Public License v3.0 or later (LICENSE).
• Documentation: GNU Free Documentation License v1.3 or later (LICENSE-DOCS).

Copyleft © 2026 Rénich Bon Ćirić <renich@evalinux.com>.

Support & Donations

If you find this shard useful and wish to support its ongoing development, please consider donating: