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:
Returns:

ActorProcessingState

Process a pipeline step

This is a streamed reply method

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

service Broker

In charge of recepting the envelopes from any actor.

Output(OutputRequest)
Arguments:
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

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:
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:
Returns:

Void
service EnvelopeStorage

Gives access to the stored envelopes

Retrieve(EnvelopePosition)
Arguments:
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

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:
Returns:

Registration
Update(RegistrationRequest)
Arguments:
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.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:
message xbus.ActorProcessRequest
Fields:
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:
message xbus.ActorReadyMsg
message xbus.ClientGetActorsReply
Fields:
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) –
  • status (Status) –
  • errors (LogMessage) –
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:
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.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:
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) –
  • triggerEmitterID (bytes) –
  • triggerEnvelopeID (bytes) –
  • pipelineID (bytes) –
  • status (Status) –
  • state (string) –
message xbus.ProcessFilter
Fields:
  • id (bytes) –
  • triggerEmitterID (bytes) –
  • triggerEnvelopeID (bytes) –
  • pipelineID (bytes) –
  • envelopeID (bytes) –
  • status (Status) –
  • statusChangedFrom (Timestamp) –
  • statusChangedTo (Timestamp) –
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.StringReply
Fields:
  • value (string) –
message xbus.SurveyRequest
Fields:
  • onlineStatus (bool) –