Introduction

zlink is a Rust crate for Varlink. If you are not familiar with Varlink, it is a simple inter-process communication (IPC) protocol: services and their clients exchange plain JSON messages over a socket. It was designed to be the simplest feasible way to make services accessible to both humans and machines, and it is seeing rapid adoption in the Linux plumbing layer — systemd alone ships more than a dozen Varlink services these days.

Unlike D-Bus, Varlink does not (typically) involve a broker or bus that relays messages between peers. Clients connect directly to the service they want to talk to, typically through a Unix domain socket. This point-to-point architecture is not just a simplification — as you will see throughout this book (especially in the Design for efficiency chapter), it enables zlink to offer an API that is leaner and more efficient than what is possible for a D-Bus implementation.

zlink is a 100% Rust-native, async-first implementation of the Varlink protocol. It provides:

• a low-level API to send and receive Varlink messages over a connection,
• high-level attribute macros — proxy for writing clients and service for writing services — that generate all the wiring for you,
• first-class support for method call pipelining,
• runtime introspection and code generation from Varlink IDL, and
• no_std support in its core, for use in embedded environments.

Crate organization

The zlink project is a Cargo workspace consisting of several crates:

• zlink: The main, unified API crate. This is the only crate you’ll typically want to depend on directly. It re-exports the appropriate subcrates based on the enabled cargo features.
• zlink-core: The no_std-capable foundation: Connection, Call, Reply, Server, Service and friends. All the other crates build on this one.
• zlink-macros: The attribute and derive macros.
• zlink-tokio: tokio-based transport implementation and runtime integration.
• zlink-smol: smol-based transport implementation and runtime integration.
• zlink-idl: Varlink interface definition language (IDL) types and parser.
• zlink-codegen: Generates Rust code from Varlink IDL files.

Since zlink re-exports everything you need, this book will only use the zlink crate in its examples. You enable your async runtime(s) through the additive cargo features tokio (the default) and smol, with the runtime-specific API of each residing in a module of the same name.

Getting help

If you need help using zlink, or just want to hang out with the cool kids, please come chat with us in the #zlink:matrix.org Matrix room. If something doesn’t seem right, please file an issue.