xbus: Core & Client API

Xbus Core & Client APIs

Note

The UUID are encoded in a binary big-endian set of 16 bytes.

Services

service ActorAgent

ActorAgent must be implemented by receiver actors (workers and consumers)

Process(ActorProcessRequest)

Arguments:

• arg – ActorProcessRequest

Returns:

ActorProcessingState

Process a pipeline step

This is a streamed reply method

If the last reply state is ‘RUNNING’, the agent MUST call ProcessingEnd

If the function returns a SERVERTOOBUSY error, xbus will attempt the same request later, with increasing delay between attempts of a same request. This can be used to implement connectors relying on external resources that may be unavailable.

service Broker

In charge of recepting the envelopes from any actor.

Output(OutputRequest)

Arguments:

• arg – OutputRequest

Returns:

EnvelopeAck

Called by an actor to send an envelope on a output

service ClientAPI

ClientAPI provides account-based methods

In some case a client may not now all the details of the account it is connected with. This service allows it to get all this information.

GetActors(Void)

Returns:

ClientGetActorsReply

GetActors lists the actors of a connected account

GetSessionToken(GetSessionTokenRequest)

Arguments:

• arg – GetSessionTokenRequest

Returns:

SessionToken

Returns a session token that can be used to reconnect later. The token is valid only for a given time that will not exceed the timeout passed as an argument. It may be revoked before the timeout.

service CoreEvents

Internal notification messages

Actor(NoRequest)

Arguments:

• arg – NoRequest

Returns:

CoreEvent

Process(NoRequest)

Arguments:

• arg – NoRequest

Returns:

CoreEvent

ProcessNodeReady(NoRequest)

Arguments:

• arg – NoRequest

Returns:

ProcessNodeReadyEvent

Envelope(NoRequest)

Arguments:

• arg – NoRequest

Returns:

EnvelopeEvent

service Director

Orchestrate the actor processings.

ProcessingEnd(ActorProcessingState)

Arguments:

• arg – ActorProcessingState

Returns:

Void

ProcessingEnd is for signaling the end of a processing by an actor.

If a node closes all its outputs, the signal is done automatically. In all other cases (errors, need to close all outputs but the one used, or consumers), it is required.

Log(ActorLogRequest)

Arguments:

• arg – ActorLogRequest

Returns:

Void

GetRunningActorRequestList(Void)

Returns:

ActorProcessRequest

service EnvelopeStorage

Gives access to the stored envelopes

Retrieve(EnvelopePosition)

Arguments:

• arg – EnvelopePosition

Returns:

EnvelopeFragmentAndPosition

Retrieve an envelope from a given position The envelope is returned as a stream of envelope fragments.

service ProcessState

Methods for an emitter to query its process states

EnvelopeStates(NoRequest)

Arguments:

• arg – NoRequest

Returns:

EmitterEnvelopeState

Emits the process states associated to an envelope

GetEnvelopeState(GetEnvelopeStateRequest)

Arguments:

• arg – GetEnvelopeStateRequest

Returns:

EmitterEnvelopeState

AckResult(AckResultRequest)

Arguments:

• arg – AckResultRequest

Returns:

Void

List(ProcessFilter)

Arguments:

• arg – ProcessFilter

Returns:

EmitterEnvelopeStateList

service Sentinel

The Sentinel service is in charge of always knowing which actors are online

Survey(NoRequest)

Arguments:

• arg – NoRequest

Returns:

SurveyRequest

All actors should subscribe to this function and act accordingly to the received SurveyRequest

ActorReady(Void)

Returns:

NoReply

Once a receiver actor is ready (ie, its ActorAgent implementation is up and subscribed), it must call this function to signal its availability to the bus

ActorLeaving(Void)

Returns:

NoReply

Before unsubscribing its ActorAgent implementation, an actor must call this function

ListActors(Void)

Returns:

ClientGetActorsReply

Returns the list of actors with their ‘online’ state updated. The reply may be delayed until the list is sure to be uptodate

service SvcRegistration

Registration API

Register(RegistrationRequest)

Arguments:

• arg – RegistrationRequest

Returns:

Registration

Update(RegistrationRequest)

Arguments:

• arg – RegistrationRequest

Returns:

Registration

service WhoAmI

A service for auto-discovering the current identity of the client when only its name or api key is known

WhoAmI(Void)

Returns:

Account

Returns the current account details. identifier can be an account name or an api key

Message types

message xbus.Account

Fields:

• id (bytes)

• name (string) – Account name Account name

• type (Type) – Account type Account type

• status (Status) – Account status Account status

• csr (string) – The certificate signing request The certificate signing request

• csrOrigin (CSROrigin)

• cert (string) – The account certificate The account certificate

• apiKey (string) – The account api key The account api key

message xbus.AckResultRequest

Fields:

• process_id (bytes)

message xbus.Actor

Fields:

• id (bytes)

• name (string)

• kind (Kind)

• status (Status)

• accountID (bytes)

• roles (string)

• lastSeen (Timestamp)

• online (bool)

• unresponsive (bool)

• config (ConfigEntry)

message xbus.ActorLogRequest

Fields:

• envelopeID (bytes)

• Context (ProcessingContext)

• messages (LogMessage)

message xbus.ActorProcessRequest

Fields:

• context (ProcessingContext)

• inputs (Input)

message xbus.Input

Fields:

• name (string) – Name of the input Name of the input

• close (bool) – True if no envelope to expect True if no envelope to expect

• envelope (Envelope) – First envelope fragment if available First envelope fragment if available

• position (EnvelopePosition) – Envelope position Envelope position

message xbus.ActorProcessingState

Fields:

• context (ProcessingContext)

• status (Status)

• messages (LogMessage)

• ActorLeaving (bool)

message xbus.ActorReadyMsg

message xbus.ClientGetActorsReply

Fields:

• actors (Actor)

message xbus.ClientGetActorsRequest

Fields:

• actorID (bytes)

message xbus.ConfigEntry

Fields:

• key (string)

• value (string)

message xbus.CoreEvent

Fields:

• name (string)

• actor (Actor)

• process (Process)

• processOldStatus (Status)

message xbus.EmitterEnvelopeState

Fields:

• processID (bytes)

• processCreatedAt (Timestamp)

• status (Status)

• errors (LogMessage)

• response (EnvelopeFragmentAndPosition)

• triggerEnvelope (EnvelopeFragmentAndPosition)

message xbus.EmitterEnvelopeStateList

Fields:

• list (EmitterEnvelopeState)

message xbus.Envelope

Fields:

• id (bytes)

• eventIDs (bytes)

• events (Event)

• last (bool)

message xbus.EnvelopeAck

Fields:

• id (bytes)

• status (ReceptionStatus)

• reason (string)

message xbus.EnvelopeEvent

Fields:

• envelopeID (bytes)

• status (Status)

• newData (bool)

message xbus.EnvelopeFragmentAndPosition

Fields:

• fragment (Envelope)

• position (EnvelopePosition)

message xbus.EnvelopePosition

Fields:

• envelope_id (bytes)

• start (bool)

• complete (bool)

• eventPositions (EventPosition)

message xbus.EnvelopeTarget

Fields:

• actorID (bytes)

• nodeID (string)

• input (string)

message xbus.Event

A message inside an envelope

Hint

Do not be confused by the name “Event”, it really is a message. The name may change in a future version of the API

Fields:

• id (bytes)

• type (string)

• index (uint64)

• itemCount (uint64)

• checksum (uint32) –

  A Castagnoli CRC32 checksum calculated on the concatenation of: A Castagnoli CRC32 checksum calculated on the concatenation of:

  • the event id binary representation

  • the event type

  • all the items

• items (bytes)

message xbus.EventPosition

Fields:

• event_id (bytes)

• index (uint64)

• itemCount (uint64)

message xbus.GetEnvelopeStateRequest

Fields:

• id (bytes)

message xbus.GetSessionTokenRequest

Fields:

• expiresIn (uint32) – request the token to expire in a number of seconds request the token to expire in a number of seconds

• invalidateToken (string) – Invalidate a previous session token Invalidate a previous session token

message xbus.LogEntry

Fields:

• envelopeID (bytes)

• actorID (bytes)

• processID (bytes)

• nodeID (string)

• message (LogMessage)

message xbus.LogMessage

A logging entry

Fields:

• time (Timestamp) – timestamp of the log entry timestamp of the log entry

• level (LogLevel) – severity level severity level

• Text (string) – entry text entry text

message xbus.OutputRequest

Fields:

• context (ProcessingContext)

• output (string)

• close (bool)

• envelope (Envelope)

message xbus.PMProcess

Fields:

• process (Process)

• level (LogLevel)

• status (Status)

• comment (string)

• logs (LogEntry)

message xbus.PipelineInfo

Fields:

• id (bytes)

• name (string)

• version (string)

• status (Status)

message xbus.Process

Fields:

• id (bytes)

• groupID (bytes)

• replayOf (bytes)

• triggerEmitterID (bytes)

• triggerEnvelopeID (bytes)

• pipelineID (bytes)

• status (Status)

• state (string)

• createdAt (Timestamp)

message xbus.ProcessFilter

Fields:

• id (bytes)

• groupID (bytes)

• replayOf (bytes)

• triggerEmitterID (bytes)

• triggerEnvelopeID (bytes)

• createdAt (TimeRange) – The time range in which the process was created The time range in which the process was created

• pipelineID (bytes)

• envelopeID (bytes)

• status (Status)

• statusChangedFrom (Timestamp) – Deprecated, should be set only if compatibility with xbus 3.0 is needed Deprecated, should be set only if compatibility with xbus 3.0 is needed

• statusChangedTo (Timestamp) – Deprecated, should be set only if compatibility with xbus 3.0 is needed Deprecated, should be set only if compatibility with xbus 3.0 is needed

• statusChanged (TimeRange) – The time range in which the process changed its status for the last time The time range in which the process changed its status for the last time

• resultAcked (bool)

message xbus.ProcessNodeReadyEvent

Fields:

• processID (bytes)

• actorID (bytes)

• nodeID (string)

message xbus.ProcessingContext

Fields:

• processID (bytes)

• nodeID (string)

message xbus.Registration

Fields:

• id (bytes)

• registrationStatus (Status)

• signedCertificate (string)

• serverCA (string)

• actorList (Actor)

message xbus.RegistrationRequest

Fields:

• name (string)

• type (Type)

• csr (string)

• actorList (Actor)

message xbus.SessionToken

Fields:

• token (string)

• validUntil (Timestamp)

message xbus.StringReply

Fields:

• value (string)

message xbus.SurveyRequest

Fields:

• onlineStatus (bool)

message xbus.TimeRange

Fields:

• from (Timestamp)

• to (Timestamp)