This is an automated email from the ASF dual-hosted git repository. suyanhanx pushed a commit to branch object-version in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 3aebdfaec66791ab0f14df1c14d665c64fdea184 Author: suyanhanx <[email protected]> AuthorDate: Thu Jul 6 21:01:38 2023 +0800 doc(rfc): object versioning Signed-off-by: suyanhanx <[email protected]> --- core/src/docs/rfcs/mod.rs | 3 ++ core/src/docs/rfcs/object_versioning.md | 76 +++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) diff --git a/core/src/docs/rfcs/mod.rs b/core/src/docs/rfcs/mod.rs index d629585ee..aca040224 100644 --- a/core/src/docs/rfcs/mod.rs +++ b/core/src/docs/rfcs/mod.rs @@ -142,3 +142,6 @@ pub mod rfc_2133_append_api {} #[doc = include_str!("2299_chain_based_operator_api.md")] pub mod rfc_2299_chain_based_operator_api {} + +#[doc = include_str!("object_versioning.md")] +pub mod rfc_object_versioning_api {} diff --git a/core/src/docs/rfcs/object_versioning.md b/core/src/docs/rfcs/object_versioning.md new file mode 100644 index 000000000..8716bbb1a --- /dev/null +++ b/core/src/docs/rfcs/object_versioning.md @@ -0,0 +1,76 @@ +Proposal Name: object versioning +Start Date: 2023-07-06 + +# Summary + +This proposal describes the object versioning (or object version control) feature of OpenDAL. + +# Motivation + +Object versioning is a common feature in many storage services. + +With object versioning, users can: + +- Track the history of an object. +- Implement optimistic concurrency control. +- Implement a simple backup system. + +# Guide-level explanation + +When object versioning is enabled, each object will have a history of versions. Each version will have a unique version ID, which is a string that is unique for each version of an object. + +The version ID is not a timestamp. It is not guaranteed to be sequential. + +When object versioning is enabled, the following operations will be supported: + +- `stat`: Get the metadata of an object with specific version ID. +- `read`: Read a specific version of an object. +- `delete`: Delete a specific version of an object. +- `list`: List all versions of an object. + +Those operations with object version are different from the normal operations: + +- `write`: when writing an object, it will always create a new version of the object than overwrite the old version. But here it is imperceptible to the user. Because the version id is generated by the service itself, it cannot be specified by the user and user cannot override the historical version. +- `stat`: when getting the metadata of an object, it will always get the metadata of the latest version of the object if no version ID is specified. +- `read`: when reading an object, it will always read the latest version of the object if no version ID is specified. +- `delete`: when deleting an object, it will always delete the latest version of the object if no version ID is specified. And users will not be able to read this object unless they specify the version ID not to be deleted. +- `list_versions`: this `list_versions` means list all versions of an object. It's an operation on a single object, and it is different from the normal `list` which means list all objects. + +```rust +// read with version ID +let content = op.read_with("path/to/file").with_version("version_id").await?; +``` + +# Reference-level explanation + +To implement object versioning, we need to add a new `with_version` field to the `stat`, `read` and `delete` method. And we need to add a new `version_id` field to the `ObjectMeta` struct. And we need to add a new `list_versions` method to the `Accessor` trait and `Operator` struct. + +```rust +// read with version ID +let content = op.read_with("path/to/file").with_version("version_id").await?; +// list all versions of an object +let versions = op.list_versions("path/to/file").await?; +``` + +# Drawbacks + +None. + +# Rationale and alternatives + +None. + +# Prior art + +- [AWS S3 Object Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) +- [Google Cloud Storage Object Versioning](https://cloud.google.com/storage/docs/object-versioning) +- [Azure Blob Storage Object Versioning](https://docs.microsoft.com/en-us/azure/storage/blobs/versioning-overview) + +# Unresolved questions + +None. + +# Future possibilities + +None. +
