sabi for Rust

A small framework for Rust designed to separate logic from data access.

It achieves this by connecting the logic layer and the data access layer via traits, similar to traditional Dependency Injection (DI). This reduces the dependency between the two, allowing them to be implemented and tested independently.

However, traditional DI often presented an inconvenience in how methods were grouped. Typically, methods were grouped by external data service like a database or by database table. This meant the logic layer had to depend on units defined by the data access layer's concerns. Furthermore, such traits often contained more methods than a specific piece of logic needed, making it difficult to tell which methods were actually used in the logic without tracing the code.

This crate addresses that inconvenience. The data access trait used by a logic function is unique to that logic, passed as an argument to the logic function. This trait declares all the data access methods that specific logic will use.

On the data access layer side, implementations can be provided in the form of default methods on DataAcc derived traits. This allows for implementation in any arbitrary unit — whether by external data service, by table, or by functional concern.

This is achieved through the following mechanism:

A DataHub struct aggregates all data access methods. DataAcc derived traits are attached to DataHub, giving DataHub the implementations of the data access methods.
Additionally, the data access traits that logic functions take as arguments are also attached to DataHub. But that alone wouldn't work in Rust because methods aren't overridden across traits, even if they have the same name and arguments, leaving the logic-facing data access trait methods without implementations.
This is where the override_macro crate comes in: it adds the method implementations of the logic-facing data access traits by calling the corresponding methods from the DataAcc derived traits. (While it's possible to implement this by hand without override_macro crate, it becomes very cumbersome for a large number of methods.)

Installation

In Cargo.toml, write this crate as a dependency:

[dependencies]
sabi-rust = "0.4.0"

Usage

1. Implementing `DataSrc` and `DataConn`

First, you'll define DataSrc which manages connections to external data services and creates DataConn. Then, you'll define DataConn which represents a session-specific connection and implements transactional operations.

use sabi::{AsyncGroup, DataSrc, DataConn};
use errs::Err;

pub struct FooDataSrc { /* ... */ }

impl DataSrc<FooDataConn> for FooDataSrc {
    fn setup(&mut self, ag: &mut AsyncGroup) -> Result<(), Err> { /* ... */ Ok(()) }
    fn close(&mut self) { /* ... */ }
    fn create_data_conn(&mut self) -> Result<Box<FooDataConn>, Err> {
        Ok(Box::new(FooDataConn{ /* ... */ }))
    }
}

pub struct FooDataConn { /* ... */ }

impl FooDataConn { /* ... */ }

impl DataConn for FooDataConn {
    fn commit(&mut self, ag: &mut AsyncGroup) -> Result<(), Err> { /* ... */ Ok(()) }
    fn rollback(&mut self, ag: &mut AsyncGroup) { /* ... */ }
    fn close(&mut self) { /* ... */ }
}

pub struct BarDataSrc { /* ... */ }

impl DataSrc<BarDataConn> for BarDataSrc {
    fn setup(&mut self, ag: &mut AsyncGroup) -> Result<(), Err> { /* ... */ Ok(()) }
    fn close(&mut self) { /* ... */ }
    fn create_data_conn(&mut self) -> Result<Box<BarDataConn>, Err> {
        Ok(Box::new(BarDataConn{ /* ... */ }))
    }
}

pub struct BarDataConn { /* ... */ }

impl BarDataConn { /* ... */ }

impl DataConn for BarDataConn {
    fn commit(&mut self, ag: &mut AsyncGroup) -> Result<(), Err> { /* ... */ Ok(()) }
    fn rollback(&mut self, ag: &mut AsyncGroup) { /* ... */ }
    fn close(&mut self) { /* ... */ }
}

2. Implementing logic functions and data traits

Define traits and functions that express your application logic. These traits are independent of specific data source implementations, improving testability. The #[overridable] macro is used to allow these trait implementations to be overridden later.

use errs::Err;
use override_macro::overridable;

#[overridable]
pub trait MyData {
    fn get_text(&mut self) -> Result<String, Err>;
    fn set_text(&mut self, text: String) -> Result<(), Err>;
}

pub fn my_logic(data: &mut impl MyData) -> Result<(), Err> {
    let text = data.get_text()?;
    let _ = data.set_text(text)?;
    Ok(())
}

3. Implementing `DataAcc` derived traits

The DataAcc trait abstracts access to data connections. The methods defined here will be used to obtain data connections via DataHub and perform actual data operations. The #[overridable] macro is also used here.

use sabi::DataAcc;
use errs::Err;
use override_macro::overridable;

use crate::data_src::{FooDataConn, BarDataConn};

#[overridable]
pub trait GettingDataAcc: DataAcc {
    fn get_text(&mut self) -> Result<String, Err> {
        let conn = self.get_data_conn::<FooDataConn>("foo")?;
        /* ... */
        Ok("output text".to_string())
    }
}

#[overridable]
pub trait SettingDataAcc: DataAcc {
    fn set_text(&mut self, text: String) -> Result<(), Err> {
        let conn = self.get_data_conn::<BarDataConn>("bar")?;
        /* ... */
        Ok(())
    }
}

4. Integrating data traits and `DataAcc` derived traits into `DataHub`

The DataHub is the central component that manages all DataSrc and DataConn, providing access to them for your application logic. By implementing the data traits (MyData) from step 2 and the DataAcc traits from step 3 on DataHub, you integrate them. The #[override_with] macro indicates that the methods of the MyData trait will be provided by the corresponding methods of the DataAcc derived traits.

use sabi::DataHub;
use override_macro::override_with;
use errs::Err;

use crate::logic_layer::MyData;
use crate::data_access_layer::{GettingDataAcc, SettingDataAcc};

impl GettingDataAcc for DataHub {}
impl SettingDataAcc for DataHub {}

#[override_with(GettingDataAcc, SettingDataAcc)]
impl MyData for DataHub {}

5. Using logic functions and `DataHub`

Inside your main function, register your global DataSrc and setup the sabi framework. Then, create an instance of DataHub and register the necessary local DataSrc using the uses method. Finally, use the txn! macro to execute your defined application logic function (my_logic) within a transaction. This automatically handles transaction commits and rollbacks.

use sabi::{uses, setup, shutdown_later, DataHub};

use crate::data_src::{FooDataSrc, BarDataSrc};
use crate::logic_layer::my_logic;

fn main() {
    // Register global DataSrc
    uses("foo", FooDataSrc{});

    // Set up the sabi framework
    // _auto_shutdown automatically closes and drops global DataSrc at the end of the scope.
    // NOTE: Don't write as `let _ = ...` because the return variable is dropped immediately.
    let _auto_shutdown = setup().unwrap();

    // Create a new instance of DataHub
    let mut data = DataHub::new();
    // Register session-local DataSrc with DataHub
    data.uses("bar", BarDataSrc{});

    // Execute application logic within a transaction
    // my_logic performs data operations via DataHub
    let _ = txn!(my_logic, data).unwrap();
}

Using this framework in async function/block

If you want to run this framework within an async function/block, you should use setup_async instead of setup, run_async! instead of run!, and txn_async! instead of txn!, as shown below.

async fn my_logic(data: &mut impl MyData) -> Result<(), Err> {
    let text = data.get_text()?;
    let _ = data.set_text(text)?;
    Ok(())
}

#[tokio::main]
async fn main() {
    // Register global DataSrc.
    uses("foo", FooDataSrc{}).await;

    // Set up the sabi framework.
    // _auto_shutdown automatically closes and drops global DataSrc at the end of the scope.
    // NOTE: Don't write as `let _ = ...` because the return variable is dropped immediately.
    let _auto_shutdown = setup_async().await.unwrap();

    // Create a new instance of DataHub.
    let mut data = DataHub::new();
    // Register session-local DataSrc with DataHub.
    data.uses("bar", BarDataSrc{});

    // Execute application logic within a transaction.
    // my_logic performs data operations via DataHub.
    let _ = txn_async!(my_logic, data).await.unwrap();
}

Supported Rust versions

This crate supports Rust 1.85.1 or later.

% cargo msrv find
  [Meta]   cargo-msrv 0.18.4
        ~~~~~~(omission)~~~~~
Result:
   Considered (min … max):   Rust 1.56.1 … Rust 1.89.0 
   Search method:            bisect                    
   MSRV:                     1.85.1                    
   Target:                   x86_64-apple-darwin

License

This program is free software under MIT License. See the file LICENSE in this distribution for more details.

sabi-rust 0.4.0