qsu

Portable service utilities with an (opinionated) service wrapper runtime.

The "What?"

The qsu ("kazoo") crate is a:

• service runtime which acts as a layer betwen the server application code and an operating system service subsystem (launchd, systemd, Windows Services), and emulates what it needs when running in a non-service (a.k.a. foreground) environment in order to avoid implementation divergence for the different environemtns.
• set of utility functions for working with services.

qsu is somewhat opinionated and is designed to make certain types of server software easier to write, but it does not aim to cover every use-case.

The "Why?"

The original motivating factors for this crate was the observation that a fair amount of time was spent on making server applications work in different service and non-service environments. This time could be better spent working on the actual server application code.

The "How?"

See design notes for a high-level overview of how the qsu wrapper runtime is implemented.

What qsu is opinionated about

It should be noted that the word opinionated does not necessary mean that qsu is forever locked to these behaviors -- it's just to say what the current version does.

All platforms

• Uses both the log crate and tracing crate.
  • log is intended for production logging.
  • tracing is intended for developer and debugging logging.
• The optional built-in command line parser assumes that there are at least three subcommands (used to register, deregister and run service).

Unixy platforms and running as a foreground process in Windows

• The following environment variables control logging/tracing:
  • LOG_LEVEL is used to control the logging level for the log crate.
  • TRACE_LEVEL is used to control the tracing level for the tracing crate.
  • If TRACE_FILE is set tracing will be directed to a file instead of being printed to the console.

Unixy platforms

• Signal management:
  • SIGINT/SIGTERM is translated to a server termination request that the server application must honor.
  • SIGHUP is interpreted as a request to "reload configuration".

Windows foreground process

• Captures Ctrl+C and Ctrl+Break and translates them to service event messages.

Windows Service

• The service installation registers the service name as an event source for the Windows Events Log.
• Application-specific configuration is stored in the registry under HKLM:\SYSTEM\CurrentControlSet\Services\[service_name]\Parameters
• Within the service's registry Parameters subkey:
  • The key LogLevel takes the role of the LOG_LEVEL environment vairable.
  • If key TraceFile and TraceLevel correspond to the environment variables TRACE_FILE and TRACE_LEVEL. Both these must be configured in the registry to enable tracing.
• Logging through log will log to the Windows Events Log.
• Logging using trace will write trace logs to a file.

When to use it, and when not to use it

To be frank, if you're writing a systemd-only service, then the value of using qsu is negligible (or it might even be wasteful to pull in qsu). The benefits of using qsu will be noticed mostly when targeting the Windows Services subsystem. But mostly the benefits become apparent when targetting multiple service subsystems in the same project, and wanting to have a similar API when developing non-async and async services.

General tips

• The logging/tracing facilities aren't initialized until the server application's runtime has been initialized, because the runtime type may affect the logging/tracing backends. As an implication of this, services that use the ArgParser should defer operations that need logging/tracking until the service handler's init() trait method is called.

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

Known limitations

• 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.

Examples

• The repository contains three different in-tree examples:
  • hellosvc is a "sync" (read: non-async) server application which dumps logs and traces every 30 seconds until the service is terminated.
  • hellosvc-tokio is the same as hellosvc, but is an async server that runs on top of tokio.
  • hellosvc-rocket is a Rocket server that writes logs and traces each time a request it made to the index page.
• The staticrocket crate uses qsu. In particular it implements the Rocket service handler, and it adds a custom application-specific subcommand to the ArgParser.

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.