Crate ruva

A event-driven framework for writing reliable and scalable system.

At a high level, it provides a few major components:

• Tools for core components with traits,
• Macros for processing events and commands

A Tour of Ruva

Ruva consists of a number of modules that provide a range of functionality essential for implementing messagebus-like applications in Rust. In this section, we will take a brief tour, summarizing the major APIs and their uses.

Command & Event

You can register any general struct with into_command attribute macro as follows:

#[ruva::into_command]
pub struct MakeOrder {
    pub user_id: i64,
    pub items: Vec<String>,
}

Only when you attach into_command attribute macro, TMessageBus will be able to understand how and where it should dispatch the command to.

To specify TEvent implementation, annotate struct with TEvent derive macro as in the following example:

use serde::Serialize;
use serde::Deserialize;
use ruva::serde_json;

#[derive(Serialize, Deserialize, Clone, ruva::TEvent)]
#[internally_notifiable]
pub struct OrderFailed {
    pub user_id: i64,
}

#[derive(Serialize, Deserialize, Clone, ruva::TEvent)]
#[externally_notifiable]
pub struct OrderSucceeded{
    #[identifier]
    pub user_id: i64,
    pub items: Vec<String>
}

Note that use of internally_notifiable(or externally_notifiable) and identifier are MUST.

• internally_notifiable is marker to let the system know that the event should be handled within the application
• externally_notifiable is to leave OutBox.
• identifier is to record aggregate id.

This results in the following method attach to the struct for example,

• to_message() : to convert the struct to heap allocated data structure so messagebus can handle them.
• state() : to record event’s state for outboxing

Initializing TCommandService

For messagebus to recognize service handler, TCommandService must be implemented, the response of which is sent directly to clients.

pub struct MessageBus {
event_handler: &'static TEventHandler<ApplicationResponse, ApplicationError>,
}

impl<C> ruva::TMessageBus<ApplicationResponse,ApplicationError,C> for MessageBus{
fn command_handler(
    &self,
    context_manager: ruva::AtomicContextManager,
    cmd: C,
) -> impl ruva::TCommandService<ApplicationResponse, ApplicationError> {
        HighestLevelOfAspectThatImplementTCommandService::new(
            MidLevelAspectThatImplementTCommandService::new(
                TargetServiceThatImplementTCommandService::new(cmd,other_depdendency)
            )
        )
}
}

For your convenience, Ruva provides declarative macros that handles transaction unit of work as you can use it as follows:

ruva::register_uow_services!(
    MessageBus,
    ServiceResponse,
    ServiceError,

    //Command => handler mapping
    CreateUserAccount => create_user_account,
    UpdatePassword => update_password,
    MakeOrder => make_order,
    DeliverProduct => deliver_product
)

Registering Event

TEvent is a side effect of TCommand or yet another TEvent processing. You can register as many handlers as possible as long as they all consume same type of Event as follows:

Example

init_event_handler!(
{
   OrderFaild: [
           NotificationHandler::send_mail,
           ],
   OrderSucceeded: [
           DeliveryHandler::checkout_delivery_items,
           InventoryHandler::change_inventory_count
           ]
}
);

In the MakeOrder TCommand Handling, we have either OrderFailed or OrderSucceeded event with their own processing handlers. Events are raised in the handlers that are thrown to TMessageBus by ContextManager. TMessageBus then loops through the handlers UNLESS StopSentinel is received.

Handler API Example

Handlers can be located anywhere as long as they accept two argument:

• msg - either TCommand or TEvent
• context - AtomicContextManager

Example

use std::marker::PhantomData;
use ruva_core::prelude::TUnitOfWork;
use ruva_core::prelude::TSetCurrentEvents;


// Service Handler
pub struct CustomHandler<R> {
    _r: PhantomData<R>,
}
impl<R> CustomHandler<R>
where
    R: TSetCurrentEvents + TUnitOfWork,
{
    pub async fn create_aggregate(
        cmd: CreateCommand,
        mut uow: R,
    ) -> Result<ApplicationResponse, ApplicationError> {
        // Transation begin
        uow.begin().await?;
        let mut aggregate: CustomAggregate = CustomAggregate::new(cmd);
        uow.add(&mut aggregate).await?;

        // Transation commit
        uow.commit().await?;
        Ok(aggregate.id.into())
    }
}

Dependency Injection(For event handlers)

For dependency to be injected into handlers, you just need to declare dependencies in crate::dependencies and specify identifiers for them. It’s worth noting that at the moment, only parameterless function or function that takes AtomicContextManager are allowed.

Example

use ruva_core::init_event_handler;
use ruva_core::prelude::TEvent;
// crate::dependencies
init_event_handler!(
    ApplicationResponse,
    ApplicationError,
    |ctx| your_dependency(ctx),

    SomethingHappened:[
        handle_this_event_handler1,
        handle_this_event_handler2,
    ],
    SomethingElseHappened:[
        handle_this_event_handler3,
        handle_this_event_handler4,
    ],
);

TMessageBus

At the core is event driven library is TMessageBus, which gets command and take raised events from object that implements TCommitHook and dispatch the event to the right handlers. As this is done only in framework side, the only way you can ‘feel’ the presence of messagebus is when you invoke it. Everything else is done magically.

Error from MessageBus

When command has not yet been regitered, it returns an error - BaseError::NotFound Be mindful that bus does NOT return the result of event processing as in distributed event processing.

Re-exports

pub extern crate static_assertions;

Modules

command

Example - simple command handler

event

serde

Serde

serde_json

Serde JSON

tokio

A runtime for writing reliable network applications without compromising speed.

tracing

A scoped, structured logging and diagnostics system.

Macros

error

init_event_handler

This macro is used to create event handler for each event.

make_conversion

make_smart_pointer

prepare_bulk_operation

register_uow_services

Structs

CommandHandler

CommandResponseWithEventFutures

Context

Local context it lasts only until logical unit of operation is done

ContextManager

Request Context Manager it lives as long as the request lives

EventMetadata

HandlerMapper

A hash map implemented with quadratic probing and SIMD lookup.

MessageBus

OutBox

SnowFlake

Enums

BaseError

EventHandlers

Traits

ApplicationError

ApplicationResponse

AsyncFunc

Deserialize

A data structure that can be deserialized from any data format supported by Serde.

Serialize

A data structure that can be serialized into any data format supported by Serde.

TAggregate

TCommand

TCommandService

Interface for messagebus to work on

TConnection

TEvent

TEventBus

TGetHandler

TMessageBus

TSetCurrentEvents

TUnitOfWork

Template for Unit of Work Concrete implementation must implement _commit method If you want to add hooks on events, you can implement process_internal_events and process_external_events

TUnitOfWorkCommandHandler

Type Aliases

AtomicContextManager

Future

FutureResult

Handlers

TEventHandler

Event handlers TEventBus work on

Attribute Macros

aggregate

Define Aggregate root

async_trait

entity

event_hook

Attribute macro for marking repository methods that collect events

into_command

Attributes will be given in the following format not specifying any attributes will result in default attributes which are Debug and Deserialize for body and Debug and Serialize for command

Derive Macros

ApplicationError

Define a Application Error type that can be used in the ruva.

ApplicationResponse

Define ApplicationResponse so that could be recognized by messagebus

Deserialize

Serialize

TConstruct

TEvent