feat(types): add stat_with API for blocking operator (#2915)

* feat(types): add stat_with API for blocking operator

* feat(types): fix code

core/src/types/operator/blocking_operator.rs

@@ -137,12 +137,53 @@ impl BlockingOperator {
     /// # }
     /// ```
     pub fn stat(&self, path: &str) -> Result<Metadata> {
+        self.stat_with(path).call()
+    }
+
+    /// Get current path's metadata **without cache** directly with extra options.
+    ///
+    /// # Notes
+    ///
+    /// Use `stat` if you:
+    ///
+    /// - Want to detect the outside changes of path.
+    /// - Don't want to read from cached metadata.
+    ///
+    /// You may want to use `metadata` if you are working with entries
+    /// returned by [`Lister`]. It's highly possible that metadata
+    /// you want has already been cached.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use anyhow::Result;
+    /// # use opendal::BlockingOperator;
+    /// use opendal::ErrorKind;
+    /// #
+    /// # #[tokio::main]
+    /// # async fn test(op: BlockingOperator) -> Result<()> {
+    /// if let Err(e) = op.stat_with("test").if_match("<etag>").call() {
+    ///     if e.kind() == ErrorKind::NotFound {
+    ///         println!("file not exist")
+    ///     }
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn stat_with(&self, path: &str) -> FunctionStat {
         let path = normalize_path(path);
 
-        let rp = self.inner().blocking_stat(&path, OpStat::new())?;
-        let meta = rp.into_metadata();
+        FunctionStat(OperatorFunction::new(
+            self.inner().clone(),
+            path,
+            OpStat::default(),
+            |inner, path, args| {
+                let rp = inner.blocking_stat(&path, args)?;
+                let meta = rp.into_metadata();
 
-        Ok(meta)
+                Ok(meta)
+            },
+        ))
     }
 
     /// Check if this path exists or not.

core/src/types/operator/operator_functions.rs

@@ -229,3 +229,34 @@ impl FunctionReader {
         self.0.call()
     }
 }
+
+/// Function that generated by [`BlockingOperator::stat_with`].
+///
+/// Users can add more options by public functions provided by this struct.
+pub struct FunctionStat(pub(crate) OperatorFunction<OpStat, Metadata>);
+
+impl FunctionStat {
+    /// Set the If-Match for this operation.
+    pub fn if_match(mut self, v: &str) -> Self {
+        self.0 = self.0.map_args(|args| args.with_if_match(v));
+        self
+    }
+
+    /// Set the If-None-Match for this operation.
+    pub fn if_none_match(mut self, v: &str) -> Self {
+        self.0 = self.0.map_args(|args| args.with_if_none_match(v));
+        self
+    }
+
+    /// Set the version for this operation.
+    pub fn version(mut self, v: &str) -> Self {
+        self.0 = self.0.map_args(|args| args.with_version(v));
+        self
+    }
+
+    /// Call the function to consume all the input and generate a
+    /// result.
+    pub fn call(self) -> Result<Metadata> {
+        self.0.call()
+    }
+}