🛠️ fix: implement `hybrid` caching and improve documentation (#244)

src/cache/cacher.rs

@@ -19,46 +19,78 @@ use super::redis_cacher::RedisCache;
 pub enum Cache {
     /// Caching is disabled
     Disabled,
-    #[cfg(feature = "redis-cache")]
+    #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
     /// Encapsulates the Redis based cache
     Redis(RedisCache),
-    #[cfg(feature = "memory-cache")]
+    #[cfg(all(feature = "memory-cache", not(feature = "redis-cache")))]
     /// Contains the in-memory cache.
     InMemory(MokaCache<String, SearchResults>),
+    #[cfg(all(feature = "redis-cache", feature = "memory-cache"))]
+    /// Contains both the in-memory cache and Redis based cache
+    Hybrid(RedisCache, MokaCache<String, SearchResults>),
 }
 
 impl Cache {
-    /// Builds the cache from the given configuration.
+    /// A function that builds the cache from the given configuration.
+    ///
+    /// # Arguments
+    ///
+    /// * `config` - It takes the config struct as an argument.
+    ///
+    /// # Returns
+    ///
+    /// It returns a newly initialized variant based on the feature enabled by the user.
     pub async fn build(_config: &Config) -> Self {
-        #[cfg(feature = "redis-cache")]
-        if let Some(url) = &_config.redis_url {
-            log::info!("Using Redis running at {} for caching", &url);
-            return Cache::new(
-                RedisCache::new(url, 5)
-                    .await
-                    .expect("Redis cache configured"),
-            );
-        }
-        #[cfg(feature = "memory-cache")]
+        #[cfg(all(feature = "redis-cache", feature = "memory-cache"))]
+        log::info!("Using a hybrid cache");
+        #[cfg(all(feature = "redis-cache", feature = "memory-cache"))]
+        return Cache::new_hybrid(
+            RedisCache::new(&_config.redis_url, 5)
+                .await
+                .expect("Redis cache configured"),
+        );
+        #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
+        log::info!("Listening redis server on {}", &_config.redis_url);
+        #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
+        return Cache::new(
+            RedisCache::new(&_config.redis_url, 5)
+                .await
+                .expect("Redis cache configured"),
+        );
+        #[cfg(all(feature = "memory-cache", not(feature = "redis-cache")))]
         {
             log::info!("Using an in-memory cache");
             return Cache::new_in_memory();
         }
-        #[cfg(not(feature = "memory-cache"))]
+        #[cfg(not(any(feature = "memory-cache", feature = "redis-cache")))]
         {
             log::info!("Caching is disabled");
             Cache::Disabled
         }
     }
 
-    /// Creates a new cache, which wraps the given RedisCache.
-    #[cfg(feature = "redis-cache")]
+    /// A function that initializes a new connection pool struct.
+    ///
+    /// # Arguments
+    ///
+    /// * `redis_cache` - It takes the newly initialized connection pool struct as an argument.
+    ///
+    /// # Returns
+    ///
+    /// It returns a `Redis` variant with the newly initialized connection pool struct.
+    #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
     pub fn new(redis_cache: RedisCache) -> Self {
         Cache::Redis(redis_cache)
     }
 
-    /// Creates an in-memory cache
-    #[cfg(feature = "memory-cache")]
+    /// A function that initializes the `in memory` cache which is used to cache the results in
+    /// memory with the search engine thus improving performance by making retrieval and caching of
+    /// results faster.
+    ///
+    /// # Returns
+    ///
+    /// It returns a `InMemory` variant with the newly initialized in memory cache type.
+    #[cfg(all(feature = "memory-cache", not(feature = "redis-cache")))]
     pub fn new_in_memory() -> Self {
         let cache = MokaCache::builder()
             .max_capacity(1000)
@@ -67,25 +99,61 @@ impl Cache {
         Cache::InMemory(cache)
     }
 
+    /// A function that initializes both in memory cache and redis client connection for being used
+    /// for managing hybrid cache which increases resiliancy of the search engine by allowing the
+    /// cache to switch to `in memory` caching if the `redis` cache server is temporarily
+    /// unavailable.
+    ///
+    /// # Arguments
+    ///
+    /// * `redis_cache` - It takes `redis` client connection struct as an argument.
+    ///
+    /// # Returns
+    ///
+    /// It returns a tuple variant `Hybrid` storing both the in-memory cache type and the `redis`
+    /// client connection struct.
+    #[cfg(all(feature = "redis-cache", feature = "memory-cache"))]
+    pub fn new_hybrid(redis_cache: RedisCache) -> Self {
+        let cache = MokaCache::builder()
+            .max_capacity(1000)
+            .time_to_live(Duration::from_secs(60))
+            .build();
+        Cache::Hybrid(redis_cache, cache)
+    }
+
     /// A function which fetches the cached json results as json string.
     ///
     /// # Arguments
     ///
     /// * `url` - It takes an url as a string.
-    pub async fn cached_json(&mut self, url: &str) -> Result<SearchResults, Report<PoolError>> {
+    ///
+    /// # Error
+    ///
+    /// Returns the `SearchResults` from the cache if the program executes normally otherwise
+    /// returns a `CacheError` if the results cannot be retrieved from the cache.
+    pub async fn cached_json(&mut self, _url: &str) -> Result<SearchResults, Report<PoolError>> {
         match self {
             Cache::Disabled => Err(Report::new(PoolError::MissingValue)),
-            #[cfg(feature = "redis-cache")]
+            #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
             Cache::Redis(redis_cache) => {
-                let json = redis_cache.cached_json(url).await?;
+                let json = redis_cache.cached_json(_url).await?;
                 Ok(serde_json::from_str::<SearchResults>(&json)
                     .map_err(|_| PoolError::SerializationError)?)
             }
-            #[cfg(feature = "memory-cache")]
-            Cache::InMemory(in_memory) => match in_memory.get(&url.to_string()) {
+            #[cfg(all(feature = "memory-cache", not(feature = "redis-cache")))]
+            Cache::InMemory(in_memory) => match in_memory.get(&_url.to_string()) {
                 Some(res) => Ok(res),
                 None => Err(Report::new(PoolError::MissingValue)),
             },
+            #[cfg(all(feature = "redis-cache", feature = "memory-cache"))]
+            Cache::Hybrid(redis_cache, in_memory) => match redis_cache.cached_json(_url).await {
+                Ok(res) => Ok(serde_json::from_str::<SearchResults>(&res)
+                    .map_err(|_| PoolError::SerializationError)?),
+                Err(_) => match in_memory.get(&_url.to_string()) {
+                    Some(res) => Ok(res),
+                    None => Err(Report::new(PoolError::MissingValue)),
+                },
+            },
         }
     }
 
@@ -96,24 +164,42 @@ impl Cache {
     ///
     /// * `json_results` - It takes the json results string as an argument.
     /// * `url` - It takes the url as a String.
+    ///
+    /// # Error
+    ///
+    /// Returns a unit type if the program caches the given search results without a failure
+    /// otherwise it returns a `CacheError` if the search results cannot be cached due to a
+    /// failure.
     pub async fn cache_results(
         &mut self,
-        search_results: &SearchResults,
-        url: &str,
+        _search_results: &SearchResults,
+        _url: &str,
     ) -> Result<(), Report<PoolError>> {
         match self {
             Cache::Disabled => Ok(()),
-            #[cfg(feature = "redis-cache")]
+            #[cfg(all(feature = "redis-cache", not(feature = "memory-cache")))]
             Cache::Redis(redis_cache) => {
-                let json = serde_json::to_string(search_results)
+                let json = serde_json::to_string(_search_results)
                     .map_err(|_| PoolError::SerializationError)?;
-                redis_cache.cache_results(&json, url).await
+                redis_cache.cache_results(&json, _url).await
             }
-            #[cfg(feature = "memory-cache")]
+            #[cfg(all(feature = "memory-cache", not(feature = "redis-cache")))]
             Cache::InMemory(cache) => {
-                cache.insert(url.to_string(), search_results.clone());
+                cache.insert(_url.to_string(), _search_results.clone());
                 Ok(())
             }
+            #[cfg(all(feature = "memory-cache", feature = "redis-cache"))]
+            Cache::Hybrid(redis_cache, cache) => {
+                let json = serde_json::to_string(_search_results)
+                    .map_err(|_| PoolError::SerializationError)?;
+                match redis_cache.cache_results(&json, _url).await {
+                    Ok(_) => Ok(()),
+                    Err(_) => {
+                        cache.insert(_url.to_string(), _search_results.clone());
+                        Ok(())
+                    }
+                }
+            }
         }
     }
 }
@@ -125,21 +211,49 @@ pub struct SharedCache {
 }
 
 impl SharedCache {
-    /// Creates a new SharedCache from a Cache implementation
+    /// A function that creates a new `SharedCache` from a Cache implementation.
+    ///
+    /// # Arguments
+    ///
+    /// * `cache` - It takes the `Cache` enum variant as an argument with the prefered cache type.
+    ///
+    /// Returns a newly constructed `SharedCache` struct.
     pub fn new(cache: Cache) -> Self {
         Self {
             cache: Mutex::new(cache),
         }
     }
 
-    /// A function which retrieves the cached SearchResulsts from the internal cache.
+    /// A getter function which retrieves the cached SearchResulsts from the internal cache.
+    ///
+    /// # Arguments
+    ///
+    /// * `url` - It takes the search url as an argument which will be used as the key to fetch the
+    /// cached results from the cache.
+    ///
+    /// # Error
+    ///
+    /// Returns a `SearchResults` struct containing the search results from the cache if nothing
+    /// goes wrong otherwise returns a `CacheError`.
     pub async fn cached_json(&self, url: &str) -> Result<SearchResults, Report<PoolError>> {
         let mut mut_cache = self.cache.lock().await;
         mut_cache.cached_json(url).await
     }
 
-    /// A function which caches the results by using the `url` as the key and
+    /// A setter function which caches the results by using the `url` as the key and
     /// `SearchResults` as the value.
+    ///
+    /// # Arguments
+    ///
+    /// * `search_results` - It takes the `SearchResults` as an argument which are results that
+    /// needs to be cached.
+    /// * `url` - It takes the search url as an argument which will be used as the key for storing
+    /// results in the cache.
+    ///
+    /// # Error
+    ///
+    /// Returns an unit type if the results are cached succesfully otherwise returns a `CacheError`
+    /// on a failure.
     pub async fn cache_results(
         &self,
         search_results: &SearchResults,