Crate ruva

source ·
Expand description

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

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

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

§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§

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§

Structs§

Enums§

Traits§

Type Aliases§

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§