The primary function of qsu ("kazoo") is to facilitate wrapping a server application into a service subsystem, such as Windows Service, systemd or launchd. In addition it offers service-related utility functions for runtime integration (like systemd unit file generation, or launchd plist generation).

A key design principle is that developers using qsu should not need to worry about platform-specific service subsystem integrations -- qsu attempts to provides a common interface for all platforms, while trying to provide idiomatic runtime behavior (such as using the Windows registry for service settings).

Features

• Integrates against systemd, luanchd and the Windows Services subsystem. It also supports running the server application outside of the platforms service subsystem (referred to as running in "foreground", which is useful for development purposes).
• qsu offers two primary runtime types:
  • Sync is for "non-async" service applications. (This is the most versatile type, and can be used to implement async services).
  • Tokio is for tokio-based async service applications.
• In addition is offers special-purpose service runtimes for:
  • Rocket is an tokio/async runtime environment with helpers for Rocket applications.
• The runtime uses two logging systems; log and tracing -- it assumes that log is used for production logs, and tracing is used for developer logs.
• It offers an optional command line argument parser, based on clap, that provides a (configurable) command line interface for registering, running and deregistering the service.
• It provides an installation module that can register/deregister services on Windows, and generate system service unit files for systemd or launcher plist files for launchd.

Known limitations

• qsu currently only supports integration against systemd (and is limited to notify and notify-reload service types), launchd and Windows Services.
• qsu is quite opinionated, and it is designed to handle "normal" service applications well at the expense of not being useful for cases that fall outside of that category.
• There are several assumptions made in qsu about paths being utf-8. Even if a public interface takes a Path or PathBuf, the function may return an error if the path isn't utf-8 compliant.

Feature labels in documentation

The crate's documentation uses automatically generated feature labels, which currently requires nightly featuers. To build the documentation locally use:

RUSTFLAGS="--cfg docsrs" RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features

Change log

The details of changes can always be found in the timeline, but for a high-level view of changes between released versions there's a manually maintained Change Log.

Project status

This crate is a work-in-progress -- still in early prototyping stage. This means potentially significant API instability between versions and incomplete, or even incorrect, documentation.

It is recommended that projects wanting to use qsu at this point use the tests and examples for up-to-date information on how to use the crate.