This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch fix-stat in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit bb1a6ac2b2052bef23c2bfb864e8c620b48ed79e Author: Xuanwo <[email protected]> AuthorDate: Tue Nov 21 16:15:36 2023 +0800 Add behavior docs Signed-off-by: Xuanwo <[email protected]> --- core/src/types/operator/blocking_operator.rs | 36 ++++++++++++++++++++++++++ core/src/types/operator/operator.rs | 38 +++++++++++++++++++++++++++- 2 files changed, 73 insertions(+), 1 deletion(-) diff --git a/core/src/types/operator/blocking_operator.rs b/core/src/types/operator/blocking_operator.rs index de5bb8d7b..0659efe8f 100644 --- a/core/src/types/operator/blocking_operator.rs +++ b/core/src/types/operator/blocking_operator.rs @@ -149,6 +149,24 @@ impl BlockingOperator { /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` /// so that we can avoid extra requests. /// + /// # Behavior + /// + /// `test` and `test/` may vary in some services such as S3. However, on a local file system, + /// they're identical. Therefore, the behavior of `stat("test")` and `stat("test/")` might differ + /// in certain edge cases. Always use `stat("test/")` when you need to access a directory if possible. + /// + /// Here are the behavior list: + /// + /// | Case | Path | Result | + /// |------------------------|-----------------|--------------------------------------------| + /// | stat existing dir | `abc/` | Metadata with dir mode | + /// | stat existing file | `abc/def_file` | Metadata with file mode | + /// | stat dir without `/` | `abc/def_dir` | Error `NotFound` or metadata with dir mode | + /// | stat file with `/` | `abc/def_file/` | Error `NotFound` | + /// | stat not existing path | `xyz` | Error `NotFound` | + /// + /// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details. + /// /// # Examples /// /// ## Check if file exists @@ -180,6 +198,24 @@ impl BlockingOperator { /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` /// so that we can avoid extra requests. /// + /// # Behavior + /// + /// `test` and `test/` may vary in some services such as S3. However, on a local file system, + /// they're identical. Therefore, the behavior of `stat("test")` and `stat("test/")` might differ + /// in certain edge cases. Always use `stat("test/")` when you need to access a directory if possible. + /// + /// Here are the behavior list: + /// + /// | Case | Path | Result | + /// |------------------------|-----------------|--------------------------------------------| + /// | stat existing dir | `abc/` | Metadata with dir mode | + /// | stat existing file | `abc/def_file` | Metadata with file mode | + /// | stat dir without `/` | `abc/def_dir` | Error `NotFound` or metadata with dir mode | + /// | stat file with `/` | `abc/def_file/` | Error `NotFound` | + /// | stat not existing path | `xyz` | Error `NotFound` | + /// + /// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details. + /// /// # Examples /// /// ## Get metadata while `ETag` matches diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index b861c5ca9..7ca46cfb7 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -164,7 +164,25 @@ impl Operator { /// /// For fetch metadata of entries returned by [`Lister`], it's better to use [`list_with`] and /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` - /// so that we can avoid extra requests. + /// so that we can avoid extra stat requests. + /// + /// # Behavior + /// + /// `test` and `test/` may vary in some services such as S3. However, on a local file system, + /// they're identical. Therefore, the behavior of `stat("test")` and `stat("test/")` might differ + /// in certain edge cases. Always use `stat("test/")` when you need to access a directory if possible. + /// + /// Here are the behavior list: + /// + /// | Case | Path | Result | + /// |------------------------|-----------------|--------------------------------------------| + /// | stat existing dir | `abc/` | Metadata with dir mode | + /// | stat existing file | `abc/def_file` | Metadata with file mode | + /// | stat dir without `/` | `abc/def_dir` | Error `NotFound` or metadata with dir mode | + /// | stat file with `/` | `abc/def_file/` | Error `NotFound` | + /// | stat not existing path | `xyz` | Error `NotFound` | + /// + /// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details. /// /// # Examples /// @@ -198,6 +216,24 @@ impl Operator { /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` /// so that we can avoid extra requests. /// + /// # Behavior + /// + /// `test` and `test/` may vary in some services such as S3. However, on a local file system, + /// they're identical. Therefore, the behavior of `stat("test")` and `stat("test/")` might differ + /// in certain edge cases. Always use `stat("test/")` when you need to access a directory if possible. + /// + /// Here are the behavior list: + /// + /// | Case | Path | Result | + /// |------------------------|-----------------|--------------------------------------------| + /// | stat existing dir | `abc/` | Metadata with dir mode | + /// | stat existing file | `abc/def_file` | Metadata with file mode | + /// | stat dir without `/` | `abc/def_dir` | Error `NotFound` or metadata with dir mode | + /// | stat file with `/` | `abc/def_file/` | Error `NotFound` | + /// | stat not existing path | `xyz` | Error `NotFound` | + /// + /// Refer to [RFC: List Prefix][crate::docs::rfcs::rfc_3243_list_prefix] for more details. + /// /// # Examples /// /// ## Get metadata while `ETag` matches
