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

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

CoreEvent

Process(NoRequest)
Arguments:
  • argNoRequest
Returns:

CoreEvent

ProcessNodeReady(NoRequest)
Arguments:
  • argNoRequest
Returns:

ProcessNodeReadyEvent

Envelope(NoRequest)
Arguments:
  • argNoRequest
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

GetRunningActorRequestList(Void)
Returns:ActorProcessRequest
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:
  • argNoRequest
Returns:

EmitterEnvelopeState

Emits the process states associated to an envelope

GetEnvelopeState(GetEnvelopeStateRequest)
Arguments:
Returns:

EmitterEnvelopeState

AckResult(AckResultRequest)
Arguments:
Returns:

Void

List(ProcessFilter)
Arguments:
Returns:

EmitterEnvelopeStateList

service Sentinel

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

Survey(NoRequest)
Arguments:
  • argNoRequest
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.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:
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:
message xbus.EmitterEnvelopeStateList
Fields:
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.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:
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) –
  • createdAt (Timestamp) –
message xbus.ProcessFilter
Fields:
  • id (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) –