stated v0.1 released

The first version of stated has been released. You can find out more about it by visiting the new website at:

http://mheily.github.io/stated/

It has been submitted for inclusion in the FreeBSD ports tree:

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=204172

Sharing state with stated

In my spare time, I've been working on a new publish/subscribe mechanism called stated (pronounced "state dee").

This mechanism allows unrelated programs to exchange information about changes to their internal state. It's not fully complete, but I think enough of the API and implementation is for people to take a look at.

I was inspired to write stated by looking at what Apple did with their notify(3) API. The basic idea is good, but there are some  problems with the Apple design, however:

1. The API design is a mix of stateless and stateful functions.
2. State information is limited to a single integer.
3. Weak security around the system namespace
4. Not easily portable due to entangling dependencies 
5. The name conflicts with an existing open source library

I'll spend the rest of this blog post discussing these problems in more detail, and showing how stated addresses the problem.

API confusion

The original design of the notify(3) API was stateless, and the ability to include state information was added later. In fact, the first sentence of the manpage still reads:

"These routines allow processes to exchange stateless notification events"

I wanted an API that was clean and focused on one thing: state change notifications. In the state(3) API, all notifications must include state information.

Not all states are integers

When it comes to the kind of state information that can be communicated, the notify(3) API is totally inadequate. You are limited to communicating state via a single unsigned integer value. By contrast, the state(3) API allows you to publish a character string of arbitrary length. This would allow you to publish a simple string as the state value, or encode a more complex set of values using JSON or XML or whatever encoding scheme you like.

To explain why this is important, imagine you have a daemon that is responsible for controlling the timezone; call it "timezoned" for example. Now imagine that you are a program that cares about the timezone, and you want to be notified whenever someone changes the timezone.

Using the state(3) API, timezoned can publish the name of the new time zone as the state, and subscribers can read this value and update their internal cache. Subscribers do not need to know the details of how/where the timezone is set; all they need to know is that the service that publishes information about the system.timezone state has told them that the new timezone is "America/New_York".

By contrast, the notify(3) API would require timezoned to coerce the current timezone into an unsigned integer. It would be up to the calling program to figure out what that means, and to do some kind of lookup to convert that into the user's preferred name for the timezone.

Insecure global namespace

The notify(3) api provides an unprotected global namespace with no isolation between the operating system and unprivileged users. Any program can impersonate any other program, and publish notifications on it's behalf.

By contrast, state(3) provides a "secure-by-default" approach to the global notification namespace. Processes running under UID 0 are considered "the system" and have full control over the global namespace. All unprivileged users are confined to their own user.uid.### namespace, and are not able to publish to the global namespace.

Entangling dependencies

The Apple implementation of libnotify is not very portable, because it depends on other Apple-specific technologies like Mach, the Apple System Logger, libdispatch, and the C blocks extension.

By contrast, stated tries to limit itself to standard POSIX facilities as much as possible. There are a few exceptions:

• kqueue(2) is used for monitoring file descriptors
• a tmpfs filesystem is used to avoid writing notification information to disk. 

A rose by any other name

The name of the Apple implementation is "libnotify", which is already the name of an existing freedesktop.org package in FreeBSD. To avoid clashing with this existing package, I decided to release my new library under the name "libstate" and the corresponding daemon named "stated". These names are not currently in use in Linux or BSD.