sabi

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.5.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) { /* ... */ }
}

pub struct BazDataSrc { /* ... */ }

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

pub struct BazDataConn { /* ... */ }

impl BazDataConn { /* ... */ }

impl DataConn for BazDataConn {
    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>;
    fn set_flag(&mut self, flag: bool) -> Result<(), Err>;
}

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

3. Implementing DataAcc derived traits

The DataAcc trait in sabi provides a simple mechanism to retrieve DataConn objects. However, it's the derived traits (like GettingDataAcc and SettingDataAcc in this example) that define the application-specific methods for accessing data. These methods then use DataAcc::get_data_conn to obtain the appropriate DataConn and perform the actual data operations. The #[overridable] macro is also used here to allow these methods to be integrated with DataHub.

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(())
    }
}

#[overridable]
pub trait UpdatingDataAcc: DataAcc {
    fn set_flag(&mut self, flag: bool) -> Result<(), Err> {
        let conn = self.get_data_conn::<BazDataConn>("baz")?;
        /* ... */
        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, UpdatingDataAcc};

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

#[override_with(GettingDataAcc, SettingDataAcc, UpdatingDataAcc)]
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, DataHub};

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

// Register global DataSrc using the `sabi::uses!` macro.
// This makes `FooDataSrc` available throughout the application.
uses!("foo", FooDataSrc{});

fn main() {
    // Register global DataSrc using the `sabi::uses` function.
    // This makes `BazDataSrc` available throughout the application.
    uses("baz", BazDataSrc{});

    // 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 using the `uses` method.
    // This makes `BarDataSrc` available only within this `DataHub` instance's session.
    data.uses("bar", BarDataSrc{});

    // Execute application logic within a transaction
    // my_logic performs data operations via DataHub by getting a text, setting it, and setting a flag.
    let _ = data.txn(my_logic).unwrap();

    // If you need to execute logic without transactional control (e.g., for read-only operations),
    // use the `run` method instead of `txn`.
    // let _ = data.run(my_logic).unwrap();
}

Supported Rust versions

This crate supports Rust 1.87.0 or later.

% ./build.sh msrv
  [Meta]   cargo-msrv 0.18.4  

Compatibility Check #1: Rust 1.75.0
  [FAIL]   Is incompatible 

Compatibility Check #2: Rust 1.84.1
  [FAIL]   Is incompatible 

Compatibility Check #3: Rust 1.89.0
  [OK]     Is compatible 

Compatibility Check #4: Rust 1.86.0
  [FAIL]   Is incompatible 

Compatibility Check #5: Rust 1.87.0
  [OK]     Is compatible 

Result:
   Considered (min … max):   Rust 1.56.1 … Rust 1.93.0 
   Search method:            bisect                    
   MSRV:                     1.87.0                    
   Target:                   x86_64-apple-darwin 

License

Copyright (C) 2024-2026 Takayuki Sato

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