Xbus connector API

This section describes the API exposed by the Xbus server to various connectors.

Warning

This documentation is deprecated and will be removed soon. The API is now automatically documented, see Xbus API.

General concepts

Connectivity

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.

Data format

All data transiting through Xbus is to be JSON serialized.

In the near future, JSON Schema is planned here.

Error management

See the response object for generalities and detailed information below for specifics when applicable.

Serialized objects

Several objects are re-used to compose communication messages. They are JSON serialized.

Envelopes

EnvelopeContext

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:

process_id UUID
ID of the process in which the envelope is being manipulated
node_id string
The pipeline node corresponding to the actor
Envelope

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.

id UUID
Unique ID of the envelope

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
context Context

A worker must copy this value from input envelopes to output envelopes.

Emitters must not set this value.

Event

An event represents a message. It is the base unit manipulated by the pipeline.

id UUID

type String

index Integer
Index of the event fragment in a splitted event

items [String]

count Integer
The amount of items this event contains.
checksum Integer
A CRC32 sum of the event

Data types

Actor

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:

id UUID
The unique ID of the actor
name String
The unique name of the actor
kind String

Kind of the actor. Can be one of:

  • emitter.
  • worker.
  • consumer.
status String

Current status of the actor. Can be one of:

  • pending.
  • enabled.
  • disabled.
  • rejected.
account_id UUID
Account to which the actor is attached
roles [String]
Roles affected to the actor
visible Boolean
True when the actor is currently visible on the bus
last_seen Iso-encoded date & time string
Last moment where the actor has been seen.

Logging

LogMessage

Message sent to the Xbus logging system.

time ISO-8601 date string

level String

Must be one of:

  • notice.
  • warning.
  • error.

text String

Responses

Response

Base type for all responses types.

status String

Status of the response. One of:

  • OK
  • ServerError
  • ClientError: Error due to the client input.
status_message String
A message explaining why the status is not “OK” (if applicable)
EnvelopeAck

Responses to envelope messages contain Response fields, plus:

id UUID
ID of the envelope
reception_status String

Indicates the reception status of the envelope. One of:

  • receiving: The envelope is still incomplete and the receiver is waiting for the remaining parts.
  • accepted: The envelope has been completely received and is guaranteed to be processed.
  • error: An error occured during the reception of immediate processing of the envelope.
reason String
A message explaining why the reception_status is error

Account / actor registration

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.

Subject
xbus.registration
Request
name String
Name of the account
type String

Type of the account. One of:

  • actor.
  • user.
  • gateway.
csr String
PEM-encoded PKCS #10 Certificate Signing Request.
actors [actor]
All the actors attached to the account.
Response

Inherits Response

registration_status String

One of:

  • pending The registration needs to be accepted by an administrator
  • accepted The registration was accepted by an administrator, the account certificate can now be used to authenticate.
  • rejected The registration was rejected by an administrator.
id UUID
Unique ID of the account. Generated by the server on the first registration attempt.
signed_certificate String
PEM-encoded X.509 certificate.
server_ca String
PEM-encoded X.509 certificate.
actors [Actor]
Updated list of actors attached to the account. The

Message emission

This section details the API involved in sending messages to the server from an emitter.

Normal envelope

Subject
xbus.msgbox.<actor-ID>.output.default, where <actor-ID> is the unique ID of the emitter
Request

A Envelope object

Can be a complete or a fragment of an envelope.

Response
A EnvelopeAck object

The emitter should ensure the registration_status field of that object is not set to error.

Closing output

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:

Close output envelope

context EnvelopeContext

last Bool
Must be set to True

Forward envelope

If a worker needs to send the same envelope it received on an input, it must send a special envelope:

Forward Envelope
id UUID
The ID of the envelope to forward

context EnvelopeContext

last Bool
Must be set to True

Message consumption

This section details APIs involved in consuming messages sent by servers to recipients (workers / consumers).

Reception

Listen subjects
Initial fragment

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.

Remaining fragments
xbus.msgbox.<actor-ID>.input.<inputname>.<envelope_id>, where <actor-ID> is the ID of the consumer, <inputname> the name of the input. and <envelope_id> is the id of the envelope.
Incoming message
A Envelope
Response
A EnvelopeAck <xbus_api_envelope_ack>`

Once an envelope is successfully received, a consumer must call the ProcessingEnd API.

ProcessingEnd

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.

Subject
xbus.actor.<actor-ID>.processingend, where <actor-ID> is the ID of the actor.

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.
Response
A Response