crystal-dbus-native

crystal dbus linux security ipc Crystal-lang gplv3 scm-rights unix-sockets zero-dependencies

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

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

Zero C-Library Dependencies: Communicates directly with Linux system and session UNIX domain sockets without libdbus-1 or libsystemd FFI bindings.
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.
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.
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.
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