This section describes the API exposed by the Xbus server to various connectors.
This document corresponds to Xbus 3.0.0.
Connectors all connect to the Xbus server to communicate; they do not need to connect between each other. The Xbus server is in charge of propagating messages from one connector to the other.
Connections are standard NATS connections secure through TLS.
All data transiting through Xbus is to be JSON serialized.
In the near future, JSON Schema is planned here.
See the response object for generalities and detailed information below for specifics when applicable.
Several objects are re-used to compose communication messages. They are JSON serialized.
Envelope context is a blackbox object that must be copied from incoming envelopes to outcoming envelopes.
Although its internal structure is not part of the API, here it is:
An envelope transits through Xbus to deliver one or multiple messages. Can be a fragment of a bigger envelope.
Aside from its “context” attribute, an envelope is immutable.
event_ids [UUID]
If provided, the complete list of event IDs of the envelope. Will be used to make sure all the pieces were properly received.
events [Event]
last Boolean
True if this is a whole envelope or the last fragment of a splitted envelope
A worker must copy this value from input envelopes to output envelopes.
Emitters must not set this value.
An event represents a message. It is the base unit manipulated by the graph.
id UUID
type String
items [String]
Actors connect to Xbus to send or receive messages. They rely on an account to handle their authentication. Here is the “Actor” structure that describes an actor:
Kind of the actor. Can be one of:
Current status of the actor. Can be one of:
LogMessage
Message sent to the Xbus logging system.
time ISO-8601 date string
- level String
Must be one of:
- notice.
- warning.
- error.
text String
Base type for all responses types.
Status of the response. One of:
Responses to envelope messages contain Response fields, plus:
Indicates the reception status of the envelope. One of:
This section details the API involved in registering an account (and if necessary, an actor) allowed to communicate with Xbus.
It should be noted that all of this may be automated by running the xbus-client program.
This API is the only one accessible by unregistered accounts.
Type of the account. One of:
Inherits Response
One of:
This section details the API involved in sending messages to the server from an emitter.
A Envelope object
Can be a complete or a fragment of an envelope.
The emitter should ensure the registration_status field of that object is not set to error.
In some case no envelope will ever be sent to a output, so the actor can explicitely close the output (or use ProcessingEnd).
This is done by sending a special envelope:
context EnvelopeContext
If a worker needs to send the same envelope it received on an input, it must send a special envelope:
context EnvelopeContext
This section details APIs involved in consuming messages sent by servers to recipients (workers / consumers).
xbus.msgbox.<actor-ID>.input.<inputname>, where <actor-ID> is the ID of the consumer, and <inputname> the name of the input.
Currently only a “default” input should be used.
Once an envelope is successfully received, a consumer must call the ProcessingEnd API.
Used by recipients (workers / consumers) to tell Xbus whether they could successfully process data, if and only if not all their output were closed.
Mandatory for consumers.
If a worker use this API, all the output on which no envelope was sent will be automatically closed.
Request
- envelope_id UUID
- The envelope that was processed
context EnvelopeContext
- result String
Final state of the processing. Must be one of:
- success.
- error.
- messages [LogMessage]
- When result is error, and only in that case, a list of log messages that may justify the error.