In-memory server for agentsPostino Port 2790 v0.1.0

Guides

Pub/sub and change notifications

Channels deliver a message to whoever is listening at that moment and keep nothing. Use them for live signals: a build finished, a run was cancelled, a key just changed. For anything a late reader must still see, use a stream.

Publish

postino publish builds "4.2 is green"
{"result":1}

The result is how many subscribers received the message. 0 means nobody was listening, and the message is gone.

Subscribe

Subscribers hold a Server-Sent Events connection. Name channels exactly, or match them with glob patterns:

postino subscribe builds deploys --pattern 'alerts.*'
data: {"channels":["builds","deploys"],"patterns":["alerts.*"],"type":"subscribed"}

data: {"channel":"builds","message":"4.2 is green","type":"message"}

data: {"channel":"alerts.disk","message":"90% full","pattern":"alerts.*","type":"pmessage"}

A connection can name up to 64 channels and patterns, and an agent token listens with at most 64 patterns across all its connections. A subscriber that cannot keep up is disconnected rather than allowed to hold messages back for everyone else: one with 256 messages, or 4 MiB, waiting to be sent. Reconnect and carry on.

PUBSUB CHANNELS, PUBSUB NUMSUB builds, and PUBSUB NUMPAT report who is listening.

Key change notifications

Every change to the keyspace is published on two channels:

  • __keyspace__:<key>, with the event name as the message: set, del, expire, expired, hset, lpush, xadd, and so on.
  • __keyevent__:<event>, with the key name as the message.

Notifications cost nothing until someone subscribes to them.

postino subscribe --pattern '__keyspace__:task:*'
__keyspace__:task:42  hset
__keyspace__:task:42  expired

An agent waiting for the plan to change subscribes to __keyspace__:plan and reads the key when the notification arrives. To find out when a lock is released, subscribe to __keyspace__:lock:deploy and wait for del or expired.