Page MenuHomePhabricator
Files F73769

SUMMARY.md
No OneTemporary
Actions

SUMMARY.md
View Options

# Store Transaction API Refactoring Summary
## Overview
The store library's transaction API has been redesigned to be more generic, composable, and extensible. The new design allows users to freely compose transactions across different store types and easily integrate custom stores.
## Key Improvements
### 1. Generic Transaction System
- **Before**: Fixed `CombinedTransaction` for only RangeStore and NamespaceStore
- **After**: Flexible `Transaction` and `ExtendedTransaction` that support any number of stores
### 2. Composable API
- **Before**: Required specific store instances in constructor
- **After**: Builder pattern with `.with_range_store()`, `.with_namespace_store()`, `.with_custom_store()`, `.with_tree()`
### 3. Type-Safe Store Access
- **Before**: Generic context methods like `assign_range()`, `reserve_namespace()`
- **After**: Store-specific contexts via `ctx.use_range()`, `ctx.use_namespace()`
### 4. Custom Store Integration
- **Before**: No support for custom stores
- **After**: `TransactionProvider` trait allows any store to participate in transactions
## API Changes
### Basic Transaction API
```rust
// New composable API
let transaction = Transaction::new()
.with_range_store(&range_store)
.with_namespace_store(&namespace_store)
.with_tree(&metadata_tree);
let result = transaction.execute(|ctx| {
let ip_bit = ctx.use_range().assign("ip_pool", "192.168.1.100")?;
let reserved = ctx.use_namespace().reserve("users", "alice", "data")?;
Ok((ip_bit, reserved))
})?;
```
### Extended Transaction API
```rust
// Support for custom stores with type identification
let transaction = ExtendedTransaction::new()
.with_range_store(&range_store)
.with_namespace_store(&namespace_store)
.with_custom_store(&audit_store, "audit")
.with_tree(&config_tree);
```
### Custom Store Integration
```rust
// 1. Implement TransactionProvider
impl TransactionProvider for MyStore {
fn transaction_trees(&self) -> Vec<&sled::Tree> {
vec![&self.tree1, &self.tree2]
}
}
// 2. Use in transactions
let transaction = ExtendedTransaction::new()
.with_custom_store(&my_store, "my_store");
```
## New Types and Traits
### Core Types
- `Transaction` - Basic transaction builder
- `ExtendedTransaction` - Advanced transaction builder with custom store support
- `TransactionContext` - Context for basic transactions
- `ExtendedTransactionContext` - Context for extended transactions
### Store-Specific Contexts
- `RangeTransactionContext` - Type-safe range operations
- `NamespaceTransactionContext` - Type-safe namespace operations
### Traits
- `TransactionProvider` - For stores to provide their trees to transactions
- `TransactionExtension` - For extending transaction contexts (advanced usage)
## Migration Path
### Legacy API (Still Supported)
```rust
let combined = CombinedTransaction::new(&range_store, &namespace_store, vec![&tree]);
combined.execute(|ctx| {
ctx.assign_range("range", "value")?;
ctx.reserve_namespace("ns", "key", "value")?;
Ok(())
})?;
```
### New API
```rust
let transaction = Transaction::new()
.with_range_store(&range_store)
.with_namespace_store(&namespace_store)
.with_tree(&tree);
transaction.execute(|ctx| {
ctx.use_range().assign("range", "value")?;
ctx.use_namespace().reserve("ns", "key", "value")?;
Ok(())
})?;
```
## Benefits
1. **Flexibility**: Compose transactions with any combination of stores
2. **Type Safety**: Store-specific contexts prevent API misuse
3. **Extensibility**: Easy integration of custom stores
4. **Maintainability**: Clear separation of concerns between store types
5. **Future-Proof**: System can accommodate new store types without API changes
## Backward Compatibility
- All existing `CombinedTransaction` code continues to work unchanged
- Legacy types are re-exported for compatibility
- Gradual migration path available
## Examples
Complete working examples are provided in the `examples/` directory:
- `simple_custom_store.rs` - Basic custom store integration (recommended)
- `extended_custom_store.rs` - Advanced patterns (demonstrates concepts)
- `custom_store.rs` - Conceptual example (demonstration only)
## Documentation
- `TRANSACTION_API.md` - Comprehensive API documentation
- `examples/README.md` - Example usage patterns and best practices
- Inline documentation with usage examples
## Testing
- All existing tests pass
- New tests cover transaction composition scenarios
- Custom store integration tests included
- Rollback behavior thoroughly tested
This refactoring provides a solid foundation for the store library to grow while maintaining backward compatibility and improving developer experience.

File Metadata

Mime Type
text/plain
Expires
Mon, Jun 9, 11:30 AM (1 d, 8 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
47642
Default Alt Text
SUMMARY.md (4 KB)

Event Timeline