Add StorageService::find method

remi/src/lib.rs

@@ -25,7 +25,10 @@
 use std::path::Path;
 
 // re-export (just in case!~)
+#[doc(hidden)]
 pub use async_trait::async_trait;
+
+#[doc(hidden)]
 pub use bytes::Bytes;
 
 mod blob;
@@ -39,7 +42,7 @@ pub use options::*;
 /// listing, etc.
 #[async_trait]
 pub trait StorageService: Send + Sync {
-    /// Represents a generic error interface to use for errors that could be emitted
+    /// Represents a generic error to use for errors that could be emitted
     /// when calling any function.
     type Error;
 
@@ -57,29 +60,71 @@ pub trait StorageService: Send + Sync {
 
     /// Optionally initialize this [`StorageService`] if it requires initialization,
     /// like creating a directory if it doesn't exist.
+    ///
+    /// * since 0.1.0
     async fn init(&self) -> Result<(), Self::Error> {
         Ok(())
     }
 
-    /// Opens a file in a given `path` and returns a Option variant of a given [`Bytes`] container.
+    /// Opens a file in the specified `path` and returns the contents as [`Bytes`] if it existed, otherwise
+    /// `None` will be returned to indicate that file doesn't exist.
+    ///
+    /// * since 0.1.0
     async fn open<P: AsRef<Path> + Send>(&self, path: P) -> Result<Option<Bytes>, Self::Error>;
 
-    /// Returns a [`Blob`] instance of the given file or directory, if it exists.
+    /// Open a file in the given `path` and returns a [`Blob`] structure if the path existed, otherwise
+    /// `None` will be returned to indiciate that a file doesn't exist.
+    ///
+    /// * since 0.1.0
     async fn blob<P: AsRef<Path> + Send>(&self, path: P) -> Result<Option<Blob>, Self::Error>;
 
-    /// Similar to [`blob`](StorageService::blob) but returns a list of blobs that exist
+    /// Iterate over a list of files from a storage service and returns a [`Vec`] of [`Blob`]s.
+    ///
+    /// * since 0.1.0
     async fn blobs<P: AsRef<Path> + Send>(
         &self,
         path: Option<P>,
         options: Option<ListBlobsRequest>,
     ) -> Result<Vec<Blob>, Self::Error>;
 
-    /// Deletes a path.
+    /// Deletes a file in a specified `path`. At the moment, `()` is returned but `bool` might be
+    /// returned to indicate if it actually deleted itself or not.
+    ///
+    /// * since 0.1.0
     async fn delete<P: AsRef<Path> + Send>(&self, path: P) -> Result<(), Self::Error>;
 
-    /// Checks whether or not if a path exists.
+    /// Checks the existence of the file by the specified path.
+    ///
+    /// * since: 0.1.0
     async fn exists<P: AsRef<Path> + Send>(&self, path: P) -> Result<bool, Self::Error>;
 
-    /// Uploads a path.
+    /// Does a file upload where it writes the byte array as one call and does not do chunking. Use the [`StorageService::multipart_upload`]
+    /// method to upload chunks by a specific size.
+    ///
+    /// * since: 0.1.0
     async fn upload<P: AsRef<Path> + Send>(&self, path: P, options: UploadRequest) -> Result<(), Self::Error>;
+
+    // /// Does a multipart upload, where it uploads chunks of data bit by bit. By default, this will in an
+    // /// unimplemented state and some storage services don't support chunk uploading.
+    // ///
+    // /// * since
+    // async fn multipart_upload<P: AsRef<Path> + Send>(&self, _path: P) -> Result<(), Self::Error> {
+    //     unimplemented!()
+    // }
+
+    /// Attempt to find a blob from a [`Blob`] where it returns the first blob that was found. A default
+    /// implementation is given which just queries all blobs via [`StorageService::blobs`] and uses the
+    /// [`find`][Iterator::find] method.
+    ///
+    /// * since: 0.6.0
+    async fn find<P: AsRef<Path> + Send, F: FnMut(&Blob) -> bool + Send>(
+        &self,
+        path: Option<P>,
+        options: Option<ListBlobsRequest>,
+        finder: F,
+    ) -> Result<Option<Blob>, Self::Error> {
+        self.blobs(path, options)
+            .await
+            .map(|blobs| blobs.into_iter().find(finder))
+    }
 }