#moondbus

#Why

• No dependency on libdbus, glib or gio
• Full control over the wire format
• A base you can build higher-level desktop integrations on

#Features

• Connection & authentication — unix socket, SASL EXTERNAL, BEGIN handshake
• Message codec — little-endian header/body encoding with correct alignment (including the g signature type's single-byte length and 8-byte struct alignment)
• Client side — Hello, RequestName, arbitrary method calls
• Server side — Server abstraction with a reusable serve() loop: connect, register a name, receive METHOD_CALLs, dispatch to your handler, and reply automatically. The moonsni tray runs on this loop.
• Server primitives — parse_header_fields, build_method_return, encode variant and a{sv} dictionaries
• Signals — emit SIGNAL messages
• Value encoder — offset-aware Encoder for building nested types (a{sv}, (ia{sv}av), variants, object paths) with correct alignment
• Message framing — reads exactly one message at a time from the stream

#Install

moon add conglinyizhi/moondbus

import {
  "conglinyizhi/moondbus/src" @dbus,
}
supported_targets = "+native"

#Quick start

///|
test "build and parse a method call" {
  // 构造一条方法调用消息
  let body = @dbus.build_variant_string("hello")
  let msg = @dbus.build_method_call(
    "com.example.Service", "/com/example/Object", "com.example.Interface", "Ping",
    body, "v", 1,
  )
  assert_true(msg.length() > 0)

  // 解析它的 header 字段
  let fields = @dbus.parse_header_fields(msg)
  match fields.interface {
    Some(i) => assert_eq(i, "com.example.Interface")
    None => fail("no interface parsed")
  }
  match fields.member {
    Some(m) => assert_eq(m, "Ping")
    None => fail("no member parsed")
  }
}

#Calling a live service

///|
fn main {
  match @dbus.connect_bus() {
    Err(e) => println("connect failed: \{e}")
    Ok(conn) => {
      match @dbus.hello(conn) {
        Err(e) => println("hello failed: \{e}")
        Ok(name) => println("our unique name: \{name}") // e.g. ":1.448"
      }

      // Ask the bus who owns a well-known name
      match
        @dbus.call_with_string(
          conn, "org.freedesktop.DBus", "/org/freedesktop/DBus", "org.freedesktop.DBus",
          "GetNameOwner", "org.kde.StatusNotifierWatcher", 2,
        ) {
        Err(e) => println("call failed: \{e}")
        Ok(m) =>
          match @dbus.read_dbus_string(m.body, 0) {
            Some(owner) => println("owner: \{owner}")
            None => println("no owner")
          }
      }
      @dbus.close(conn)
    }
  }
}

#API overview

#Connection

#Calls

#Messages

#Encoding values

///|
test "encode a{sv} dictionary" {
  let e = @dbus.Encoder::new()
  e.array_with(8, fn(dict) {
    dict.struct_with(fn(kv) {
      kv.string("Title")
      kv.variant_string("My App")
    })
    dict.struct_with(fn(kv) {
      kv.string("Menu")
      kv.variant_object_path("/MenuBar")
    })
  })
  let body = e.finish()
  assert_true(body.length() > 0)
}

#Emitting signals

///|
test "build an a{sv} body for a signal" {
  // encode_layout 需要的 body (u ui) 示例：用 build_body_uu 构造
  let body = @dbus.build_body_uu(2, 0)
  assert_true(body.length() > 0)
}

#Implementing a D-Bus service

///|
test "server dispatch" {
  let r = dispatch_ping("com.example", "Ping")
  if r is Some(reply) {
    assert_eq(reply.signature, "v")
  } else {
    fail("expected reply")
  }
}

///|
/// 模拟服务分发：Ping 返回 pong，其它不回。
fn dispatch_ping(iface : String, member : String) -> @dbus.Reply? {
  if iface == "com.example" && member == "Ping" {
    Some(@dbus.Reply::make(@dbus.build_variant_string("pong"), "v"))
  } else {
    None // unknown method: no reply
  }
}

#Status & limitations

• Session bus over unix socket, EXTERNAL auth
• Method calls with s, su bodies
• Replies with v, a{sv}, and arbitrary nested types via Encoder
• Emitting signals
• Object export — verified against the StatusNotifierItem and com.canonical.dbusmenu specs (see moonsni)

• System bus address parsing (the session bus path is currently fixed)
• Receiving / matching signals (AddMatch)
• Decoding arbitrary types (only strings and u32 are decoded today)
• 64-bit integers, doubles, file descriptors
• Non-EXTERNAL authentication mechanisms

#Platform

• The session-bus unix-socket path (/run/user/<uid>/bus) works on the dev machine.
• Not tested against the system bus, a different session bus address, or a differently-configured dbus-daemon.
• Not tested on other platforms: no Windows (D-Bus uses TCP loopback there, not unix sockets) or macOS testing has been done.
• The wire codec is exercised by unit tests (alignment / round-trips / robust parsing) but not validated against a third-party D-Bus implementation's byte-for-byte output.

#License