1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
use async_trait::async_trait;
use serde::{de::DeserializeOwned, Serialize};
use std::fmt::{Debug, Display};

use crate::{Config, TapestryFragment, TapestryId};

#[cfg(feature = "rocksdb")]
pub mod rocksdb;

/// A storage handler trait designed for saving and retrieving fragments of a tapestry.
///
/// # Usage
///
/// Implementations of `TapestryChestHandler` should provide the storage and retrieval mechanisms
/// tailored to specific use-cases or storage backends, such as databases, file systems, or
/// in-memory stores.
#[async_trait]
pub trait TapestryChestHandler<T: Config> {
	/// Defines the error type returned by the handler methods.
	type Error: Display + Debug;

	fn new() -> Self;

	/// Saves a tapestry fragment.
	///
	/// Tapestry fragments are stored incrementally, also refered to as "instances". Each instance
	/// is identified by an integer, starting at 1 and incrementing by 1 for each new instance.
	///
	/// This method is executed primarily by the [`crate::Loom::weave`] function.
	///
	/// # Parameters
	///
	/// - `tapestry_id`: Identifies the tapestry.
	/// - `tapestry_fragment`: An instance of `TapestryFragment` to be stored.
	/// - `increment`:
	///     - A boolean flag indicating whether the tapestry instance should be incremented.
	///     - This should typically be `true` when saving a new instance of [`TapestryFragment`],
	///       and `false` when updating an existing one.
	async fn save_tapestry_fragment<TID: TapestryId>(
		&self,
		tapestry_id: &TID,
		tapestry_fragment: TapestryFragment<T>,
		increment: bool,
	) -> crate::Result<u64>;
	/// Save tapestry metadata.
	///
	/// Based on application use cases, you can add aditional data for a given [`TapestryId`]
	async fn save_tapestry_metadata<TID: TapestryId, M: Serialize + Debug + Clone + Send + Sync>(
		&self,
		tapestry_id: TID,
		metadata: M,
	) -> crate::Result<()>;
	/// Retrieves the index of a tapestry.
	///
	/// Returns None if the tapestry does not exist.
	async fn get_instance_index<TID: TapestryId>(
		&self,
		tapestry_id: TID,
	) -> crate::Result<Option<u16>>;
	/// Retrieves the last tapestry fragment, or a fragment at a specified instance.
	///
	/// # Parameters
	///
	/// - `tapestry_id`: Identifies the tapestry.
	/// - `instance`: The instance of the fragment to retrieve. If `None`, the method should
	///   retrieve the last fragment.
	///
	/// # Returns
	///
	/// On successful retrieval, it returns `Ok(Some(TapestryFragment))` or `Ok(None)` if no
	/// fragment was found.
	async fn get_tapestry_fragment<TID: TapestryId>(
		&self,
		tapestry_id: TID,
		instance: Option<u64>,
	) -> crate::Result<Option<TapestryFragment<T>>>;
	/// Retrieves the last tapestry metadata, or a metadata at a specified instance.
	async fn get_tapestry_metadata<TID: TapestryId, M: DeserializeOwned + Send + Sync>(
		&self,
		tapestry_id: TID,
	) -> crate::Result<Option<M>>;
	/// Deletes a tapestry and all its instances.
	async fn delete_tapestry<TID: TapestryId>(&self, tapestry_id: TID) -> crate::Result<()>;
	/// Deletes a tapestry fragment.
	async fn delete_tapestry_fragment<TID: TapestryId>(
		&self,
		tapestry_id: TID,
		instance: Option<u64>,
	) -> crate::Result<()>;
}