Skip to end of metadata
Go to start of metadata

ErraiBus implements a JSON-based wire protocol which is used for the federated communication between different buses. The protocol specification encompasses a standard JSON payload structure, a set of verbs, and an object marshalling protocol. The protocol is named J.REP. Which stands for JSON Rich Event Protocol.

Payload Structure

All wire messages sent across are assumed to be JSON arrays at the outermost element, contained in which, there are 0..n messages. An empty array is considered a no-operation, but should be counted as activity against any idle timeout limit between federated buses.

Figure 1 - Example J.REP Payload
  {"ToSubject" : "SomeEndpoint", "Value" : "SomeValue" },
  {"ToSubject" : "SomeOtherEndpoint", "Value" : "SomeOtherValue"}

In Figure 1, we see an example of a J.REP payload containing two messages. One bound for an endpoint named "SomeEndpoint" and the other bound for the endpoint "SomeOtherEndpoint". They both include a payload element "Value" which contain strings. Let's take a look at the anatomy of an individual message.

Figure 2 - An J.REP Message
  "ToSubject" : "TopicSubscriber",
  "CommandType" : "Subscribe",
  "Value " : "happyTopic",
  "ReplyTo" : "MyTopicSubscriberReplyTo"

The message shown in Figure 2 shows a very vanilla J.REP message. The keys of the JSON Object represent individual message parts, with the values representing their corresponding values. The standard J.REP protocol encompasses a set of standard message parts and values, which for the purposes of this specification we'll collectively refer to as the protocol verbs.

The following table describes all of the message parts that a J.REP capable client is expected to understand:

Part Required JSON Type Description
ToSubject Yes String Specifies the subject within the bus, and its federation, which the message should be routed to.
CommandType No String Specifies a command verb to be transmitted to the receiving subject. This is an optional part of a message contract, but is required for using management services
ReplyTo No String Specifies to the receiver what subject it should reply to in response to this message.
Value No Any A recommended but not required standard payload part for sending data to services
PriorityProcessing No Number A processing order salience attribute. Messages which specify priority processing will be processed first if they are competing for resources with other messages in flight. Note: the current version of ErraiBus only supports two salience levels (0 and >1). Any non-zero salience in ErraiBus will be given the same priority relative to 0 salience messages
ErrorMessage No String An accompanying error message with any serialized exception
Throwable No Object If applicable, an encoded object representing any remote exception that was thrown while dispatching the specified service

Built-in Subjects

The table contains a list of reserved subject names used for facilitating things like bus management and error handling. A bus should never allow clients to subscribe to these subjects directly.

Subject Description
ClientBus The self-hosted message bus endpoint on the client
ServerBus The self-hosted message bus endpoint on the server
ClientBusErrors The standard error receiving service for clients

As this table indicates, the bus management protocols in J.REP are accomplished using self-hosted services. See the section on Bus Management and Handshaking Protocols for details.

Message Routing

There is no real distinction in the J.REP protocol between communication with the server, versus communication with the client. In fact, it assumed from an architectural standpoint that there is no real distinction between a client and a server. Each bus participates in a flat-namespaced federation. Therefore, it is possible that a subject may be observed on both the server and the client.

One in-built assumption of a J.REP-compliant bus however, is that messages are routed within the auspices of session isolation. Consider the following diagram:

In Figure 3, is is possible for Client A to send messages to the subjects ServiceA and ServiceB. But it is not possible to address messages to ServiceC. Conversely, Client B can address messages to ServiceC and ServiceB, but not ServiceA.

Bus Management and Handshaking Protocols

Federation between buses requires management traffic to negotiate connections and manage visibility of services between buses. This is accomplished through services named ClientBus and ServerBus which both implement the same protocol contracts which are defined in this section.

ServerBus and ClientBus commands

Both bus services share the same management protocols, by implementing verbs (or commands) that perform different actions. These are specified in the protocol with the CommandType message part. The following table describes these commands:

Command / Verb Message Parts Description
ConnectToQueue N/A The first message sent by a connecting client to begin the handshaking process.
CapabilitiesNotice CapabilitiesFlags A message sent by one bus to another to notify it of its capabilities during handshake (for instance long polling or websockets)
FinishStateSync N/A A message sent from one bus to another to indicate that it has now provided all necessary information to the counter-party bus to establish the federation. When both buses have sent this message to each other, the federation is considered active.
RemoteSubscribe Subject or SubjectsList A message sent to the remote bus to notify it of a service or set of services which it is capable of routing to.
RemoteUnsubscribe Subject A message sent to the remote bus to notify it that a service is no longer available.
Disconnect Reason A message sent to a server bus from a client bus to indicate that it wishes to disconnect and defederate. Or, when sent from the client to server, indicates that the session has been terminated.
SessionExpired N/A A message sent to a client bus to indicate that its messages are no longer being routed because it no longer has an active session
Heartbeat N/A A message sent from one bus to another periodically to indicate it is still active.

Message Parts for Bus Commands:

Part Required JSON Type Description
CapabilitiesFlags Yes String A comma delimited string of capabilities the bus is capable of us
Subject Yes String The subject to subscribe or unsubscribe from
SubjectsList Yes Array An array of strings representing a list of subjects to subscribe to
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.