Events

Moera client may connect to WebSockets endpoint of a node to receive events about everything happening at the node right now: new and updated posts, changed settings etc. This allows client to be more responsive. Typically the client connects to the home node (authentication token is required) and to the node the user views at the moment.

Moera uses STOMP protocol with several additional headers. Any STOMP client should be compatible.

Connecting

Client opens a WebSockets connection to the endpoint located at /events under Moera API root. Then it sends CONNECTED STOMP frame with the following headers:

  • accept-version: - as per STOMP specification;
  • host: - is required to differentiate between virtual domains at the same server;
  • token: - authentication token, if available
  • heart-beat: - recommended, as per STOMP specification.

Subscribing

After successful connection, the client sends SUBSCRIBE STOMP frame with the following headers:

  • id: - as per STOMP specification;
  • destination: /user/queue - required;
  • seen: <queueStartedAt>,<lastEvent> - in the case of reconnection, the client tells the node the queue timestamp and the number of the last event it received from this node. If possible, the node resends all events that the client lost while being disconnected.

Event packet

Events are send to the client in MESSAGE frames. Each frame contains event packet in JSON form with the following fields:

Type Field Comment
timestamp queueStartedAt The timestamp of the moment when the current event queue was created on the node side. This value is typically changed when the node is restarted. In this case event numbers start again from 0, but combination with the queue timestamp makes them unique.
int ordinal The event ordinal number.
timestamp sentAt The event timestamp.
String cid The client ID. If the event was created as a result of processing a REST API request of some client, this field will contain a copy of cid parameter passed with the request. This mechanism allows client to know that the event is a result of processing its own request. Usually such events are ignored, because they contain information already known to the client.
Event event The event structure itself, see below.

Event

The event structure consists of type field, containing the type of the event and zero or more additional fields, containing more detailed information. See their description below.

Events typically contain minimal amount of information. Since many events are not relevant to the client and are ignored, including too much information would be waste of traffic. The client may make a REST API request, if needed.

SUBSCRIBED

Sent immediately after subscribing to update the client about the current queue state and its STOMP session ID.

Authentication:
the subscriber only
Type Field Comment
String sessionId STOMP session ID

PROFILE_UPDATED

Profile was updated.

Authentication:
none

NODE_SETTINGS_CHANGED

Some node settings were changed.

Authentication:
admin

CLIENT_SETTINGS_CHANGED

Some client settings were changed.

Authentication:
admin

POSTING_ADDED

A posting was added.

Authentication:
none
Type Field Comment
String id the posting ID
int moment the posting moment

POSTING_UPDATED

A posting was updated.

Authentication:
none
Type Field Comment
String id the posting ID
int moment the posting moment

POSTING_DELETED

A posting was deleted.

Authentication:
none
Type Field Comment
String id the posting ID
int moment the posting moment

POSTING_RESTORED

A deleted posting was restored.

Authentication:
none
Type Field Comment
String id the posting ID
int moment the posting moment

REGISTERED_NAME_CHANGED

The registered name of the node was changed.

Authentication:
none
Type Field Comment
String name the new name

REGISTERED_NAME_OPERATION_STATUS

Status of an operation on the registered name of the node was changed.

Authentication:
admin

REMOTE_POSTING_VERIFIED

Signature of a posting on a remote node was verified.

Authentication:
admin
Type Field Comment
String id asynchronous operation ID
String nodeName the remote node name
String receiverName the posting receiver name
String postingId the posting ID
String revisionId the posting revision ID
boolean correct verification result

REMOTE_POSTING_VERIFICATION_FAILED

Verification of the signature of a posting on a remote node failed.

Authentication:
admin
Type Field Comment
String id asynchronous operation ID
String nodeName the remote node name
String receiverName the posting receiver name
String postingId the posting ID
String revisionId the posting revision ID
String errorCode error code
String errorMessage error message