We need 'one-time subscriptions' for some different tasks to inform a client about server-side events.

The main feature of the subscriptions is a one-time action. So if the server generates too many events and a client is too slow, the server will not allocate additional memory.

Each subscription is defined by "key". "key" is always a string constant. To provide the functional, we add some methods to IPROTO protocol:

Protocol

• IPROTO_SUBSCRIBE_ONCE (client to server)
  The request is used to subscribe a client for one or more events. The request body contains an array of strings for all keys that a client needs.

Each received event will unsubscribe a client from its "key", so a client has to resend the request after each event.

IPROTO_OK-response for the request and IPROTO_EVENTS (see below) have the same format.

• IPROTO_UNSUBSCRIBE (client to server)
  The request is used to unsubscribe a client from one or more events.
  The request body format for IPROTO_SUBSCRIBE_ONCE and IPROTO_UNSUBSCRIBE are the same.

• IPROTO_EVENTS (server to client)
  The package is used as a response to IPROTO_SUBSCRIBE_ONCE and as a notification about happened events.
  The package body contains a map of event keys and event data.

Lua client API server-side

So, we need a few methods:

box.broadcast_event(key[, data])
box.broadcast_state(key[, data])

box.send_event(session, key[, data])
box.send_event(sid, key[, data])

box.send_state(session, key[, data])
box.send_state(sid, key[, data])

The system can pass events or states through itself. There is a cache for states to send a state through the system. "send_state" and "broadcast_state" apply the following algorithm:
Save new state into the cache.
Send the event to all (or selected) subscribed clients.

Lua client API client-side (net.box)

nb:on_event(key_name, callback) - installs triggers for each key
nb:subscribe_once(key1[, key2, ...]) - subscribe keys. The method returns the map that was returned by IPROTO_OK response (see above)
nb:unsubscribe(key1[, key2, ...]) - unsubscribe keys