You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2026/08/25 10:22:17 UTC

(opendal) 01/01: feat(services/s3): support object restoration

This is an automated email from the ASF dual-hosted git repository.

Xuanwo pushed a commit to branch xuanwo/restore-s3
in repository https://gitbox.apache.org/repos/asf/opendal.git

commit cbf214cb8c72cabbd1fb8b5cfe98892e7535cc61
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Aug 25 18:21:34 2026 +0800

    feat(services/s3): support object restoration
---
 .github/services/s3/0_minio_s3/action.yml          |   2 +-
 .github/services/s3/aws_s3/action.yml              |   2 +-
 .../s3/aws_s3_with_list_objects_v1/action.yml      |   2 +-
 .github/services/s3/aws_s3_with_sse_c/action.yml   |   2 +-
 .../s3/aws_s3_with_virtual_host/action.yml         |   2 +-
 .../services/s3/ceph_rados_s3/disable_action.yml   |   2 +-
 .../services/s3/minio_s3_with_anonymous/action.yml |   2 +-
 .../s3/minio_s3_with_list_objects_v1/action.yml    |   2 +-
 .../s3/minio_s3_with_versioning/action.yml         |   2 +-
 .github/services/s3/r2/disabled_action.yml         |   2 +-
 .github/services/s3/seaweedfs_s3/action.yml        |   2 +-
 core/core/src/blocking/operator.rs                 |  12 +
 core/core/src/docs/rfcs/7182_restore_api.md        | 696 ++++-----------------
 core/core/src/layers/capability_override.rs        |   9 +
 core/core/src/layers/complete.rs                   |   9 +
 core/core/src/layers/correctness_check.rs          |  32 +
 core/core/src/layers/error_context.rs              |  13 +
 core/core/src/layers/simulate.rs                   |   9 +
 core/core/src/raw/accessor.rs                      |  47 ++
 core/core/src/raw/operation.rs                     |   3 +
 core/core/src/raw/ops.rs                           |  45 ++
 core/core/src/raw/rps.rs                           |  11 +
 core/core/src/types/capability.rs                  |   7 +
 core/core/src/types/operator/operator.rs           |  88 +++
 core/core/src/types/operator/operator_futures.rs   |  19 +
 core/core/src/types/options.rs                     |  23 +
 core/layers/async-backtrace/src/lib.rs             |  10 +
 core/layers/await-tree/src/lib.rs                  |  12 +
 core/layers/capability-check/src/lib.rs            |  25 +
 core/layers/chaos/src/lib.rs                       |   9 +
 core/layers/concurrent-limit/src/lib.rs            |  10 +
 core/layers/dtrace/src/lib.rs                      |   9 +
 core/layers/fastrace/src/lib.rs                    |  10 +
 core/layers/foyer/src/lib.rs                       |  40 +-
 core/layers/hotpath/src/lib.rs                     |  10 +
 core/layers/immutable-index/src/lib.rs             |   9 +
 core/layers/logging/src/lib.rs                     |  12 +
 core/layers/mime-guess/src/lib.rs                  |   9 +
 core/layers/observe-metrics-common/src/lib.rs      |  35 ++
 core/layers/oteltrace/src/lib.rs                   |  14 +
 core/layers/retry/src/lib.rs                       |  23 +
 core/layers/route/src/lib.rs                       |  12 +
 core/layers/tail-cut/src/lib.rs                    |   9 +
 core/layers/throttle/src/lib.rs                    |   9 +
 core/layers/timeout/src/lib.rs                     |  10 +
 core/layers/tracing/src/lib.rs                     |  10 +
 core/services/s3/src/backend.rs                    |  85 +++
 core/services/s3/src/docs.md                       |  25 +
 core/tests/behavior/async_restore.rs               | 162 +++++
 core/tests/behavior/main.rs                        |   2 +
 50 files changed, 1037 insertions(+), 569 deletions(-)

diff --git a/.github/services/s3/0_minio_s3/action.yml b/.github/services/s3/0_minio_s3/action.yml
index 390e0c929..ec964ff17 100644
--- a/.github/services/s3/0_minio_s3/action.yml
+++ b/.github/services/s3/0_minio_s3/action.yml
@@ -43,5 +43,5 @@ runs:
         OPENDAL_S3_ACCESS_KEY_ID=minioadmin
         OPENDAL_S3_SECRET_ACCESS_KEY=minioadmin
         OPENDAL_S3_REGION=us-east-1
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
         EOF
diff --git a/.github/services/s3/aws_s3/action.yml b/.github/services/s3/aws_s3/action.yml
index af13dbe1f..8449750a8 100644
--- a/.github/services/s3/aws_s3/action.yml
+++ b/.github/services/s3/aws_s3/action.yml
@@ -36,4 +36,4 @@ runs:
     - name: Add capability overrides
       shell: bash
       run: |
-        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false" >> $GITHUB_ENV
+        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false" >> $GITHUB_ENV
diff --git a/.github/services/s3/aws_s3_with_list_objects_v1/action.yml b/.github/services/s3/aws_s3_with_list_objects_v1/action.yml
index fb5dd359d..49bdf7a34 100644
--- a/.github/services/s3/aws_s3_with_list_objects_v1/action.yml
+++ b/.github/services/s3/aws_s3_with_list_objects_v1/action.yml
@@ -37,4 +37,4 @@ runs:
       shell: bash
       run: |
         echo "OPENDAL_S3_DISABLE_LIST_OBJECTS_V2=true" >> $GITHUB_ENV
-        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false" >> $GITHUB_ENV
+        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false" >> $GITHUB_ENV
diff --git a/.github/services/s3/aws_s3_with_sse_c/action.yml b/.github/services/s3/aws_s3_with_sse_c/action.yml
index 0380803af..1e2ad1f46 100644
--- a/.github/services/s3/aws_s3_with_sse_c/action.yml
+++ b/.github/services/s3/aws_s3_with_sse_c/action.yml
@@ -40,5 +40,5 @@ runs:
         OPENDAL_S3_SERVER_SIDE_ENCRYPTION_CUSTOMER_ALGORITHM=AES256
         OPENDAL_S3_SERVER_SIDE_ENCRYPTION_CUSTOMER_KEY=MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA=
         OPENDAL_S3_SERVER_SIDE_ENCRYPTION_CUSTOMER_KEY_MD5=zZ5FnqcIqUjVwvWmyog4zw==
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false
         EOF
diff --git a/.github/services/s3/aws_s3_with_virtual_host/action.yml b/.github/services/s3/aws_s3_with_virtual_host/action.yml
index 0c2966a99..87d72d7ff 100644
--- a/.github/services/s3/aws_s3_with_virtual_host/action.yml
+++ b/.github/services/s3/aws_s3_with_virtual_host/action.yml
@@ -37,4 +37,4 @@ runs:
       shell: bash
       run: |
         echo "OPENDAL_S3_ENABLE_VIRTUAL_HOST_STYLE=on" >> $GITHUB_ENV
-        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false" >> $GITHUB_ENV
+        echo "OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false" >> $GITHUB_ENV
diff --git a/.github/services/s3/ceph_rados_s3/disable_action.yml b/.github/services/s3/ceph_rados_s3/disable_action.yml
index 73f9017e9..cf2c85a9c 100644
--- a/.github/services/s3/ceph_rados_s3/disable_action.yml
+++ b/.github/services/s3/ceph_rados_s3/disable_action.yml
@@ -41,5 +41,5 @@ runs:
         OPENDAL_S3_ACCESS_KEY_ID=demo
         OPENDAL_S3_SECRET_ACCESS_KEY=demo
         OPENDAL_S3_REGION=us-east-1
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_with_if_match=false,write_can_append=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_with_if_match=false,write_can_append=false
         EOF
diff --git a/.github/services/s3/minio_s3_with_anonymous/action.yml b/.github/services/s3/minio_s3_with_anonymous/action.yml
index fc0ee27a5..bb4ae851a 100644
--- a/.github/services/s3/minio_s3_with_anonymous/action.yml
+++ b/.github/services/s3/minio_s3_with_anonymous/action.yml
@@ -49,5 +49,5 @@ runs:
         OPENDAL_S3_REGION=us-east-1
         OPENDAL_S3_ALLOW_ANONYMOUS=on
         OPENDAL_S3_DISABLE_EC2_METADATA=on
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
         EOF
diff --git a/.github/services/s3/minio_s3_with_list_objects_v1/action.yml b/.github/services/s3/minio_s3_with_list_objects_v1/action.yml
index 11c6c2855..910001b6d 100644
--- a/.github/services/s3/minio_s3_with_list_objects_v1/action.yml
+++ b/.github/services/s3/minio_s3_with_list_objects_v1/action.yml
@@ -44,5 +44,5 @@ runs:
         OPENDAL_S3_SECRET_ACCESS_KEY=minioadmin
         OPENDAL_S3_REGION=us-east-1
         OPENDAL_S3_DISABLE_LIST_OBJECTS_V2=true
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
         EOF
diff --git a/.github/services/s3/minio_s3_with_versioning/action.yml b/.github/services/s3/minio_s3_with_versioning/action.yml
index f3997717b..eacf6eefc 100644
--- a/.github/services/s3/minio_s3_with_versioning/action.yml
+++ b/.github/services/s3/minio_s3_with_versioning/action.yml
@@ -44,5 +44,5 @@ runs:
         OPENDAL_S3_ACCESS_KEY_ID=minioadmin
         OPENDAL_S3_SECRET_ACCESS_KEY=minioadmin
         OPENDAL_S3_REGION=us-east-1
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,delete_with_if_match=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=write_can_append=false,copy_with_if_not_exists=false,copy_with_if_match=false,restore_with_if_not_exists=false,delete_with_if_match=false
         EOF
diff --git a/.github/services/s3/r2/disabled_action.yml b/.github/services/s3/r2/disabled_action.yml
index f9952414e..ad8da0125 100644
--- a/.github/services/s3/r2/disabled_action.yml
+++ b/.github/services/s3/r2/disabled_action.yml
@@ -38,5 +38,5 @@ runs:
       run: |
         cat << EOF >> $GITHUB_ENV
         OPENDAL_S3_REGION=auto
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false,delete_max_size=700,stat_with_override_cache_control=false,stat_with_override_content_disposition=false,stat_with_override_content_type=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false,delete_max_size=700,stat_with_override_cache_control=false,stat_with_override_content_disposition=false,stat_with_override_content_type=false
         EOF
diff --git a/.github/services/s3/seaweedfs_s3/action.yml b/.github/services/s3/seaweedfs_s3/action.yml
index 8605ffc75..4f5d64c63 100644
--- a/.github/services/s3/seaweedfs_s3/action.yml
+++ b/.github/services/s3/seaweedfs_s3/action.yml
@@ -35,5 +35,5 @@ runs:
         OPENDAL_S3_ACCESS_KEY_ID=seaweedfsadmin
         OPENDAL_S3_SECRET_ACCESS_KEY=seaweedfsadmin
         OPENDAL_S3_REGION=us-east-1
-        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,write_can_append=false
+        OPENDAL_TEST_CAPABILITY_OVERRIDES=stat_with_version=false,read_with_version=false,delete_with_version=false,list_with_versions=false,list_with_deleted=false,copy_with_source_version=false,restore=false,restore_with_version=false,restore_with_if_not_exists=false,write_can_append=false
         EOF
diff --git a/core/core/src/blocking/operator.rs b/core/core/src/blocking/operator.rs
index 1fbba15ea..087695ff5 100644
--- a/core/core/src/blocking/operator.rs
+++ b/core/core/src/blocking/operator.rs
@@ -654,6 +654,18 @@ impl Operator {
         self.spawn_block(async move { op.rename_options(&from, &to, opts).await })?
     }
 
+    /// Restore the given path from its latest deleted state.
+    pub fn restore(&self, path: &str) -> Result<()> {
+        self.restore_options(path, options::RestoreOptions::default())
+    }
+
+    /// Restore the given path with additional options.
+    pub fn restore_options(&self, path: &str, opts: options::RestoreOptions) -> Result<()> {
+        let op = self.op.clone();
+        let path = path.to_string();
+        self.spawn_block(async move { op.restore_options(&path, opts).await })?
+    }
+
     /// Delete given path.
     ///
     /// # Notes
diff --git a/core/core/src/docs/rfcs/7182_restore_api.md b/core/core/src/docs/rfcs/7182_restore_api.md
index b91810c8b..9c30b220a 100644
--- a/core/core/src/docs/rfcs/7182_restore_api.md
+++ b/core/core/src/docs/rfcs/7182_restore_api.md
@@ -1,650 +1,232 @@
 - Proposal Name: (`restore_api`)
 - Start Date: 2025-02-04
-- RFC PR: [apache/opendal#7178](https://github.com/apache/opendal/pull/7178)
+- RFC PR: [apache/opendal#7182](https://github.com/apache/opendal/pull/7182)
 - Tracking Issue: [apache/opendal#4321](https://github.com/apache/opendal/issues/4321)
 
 # Summary
 
-Implement restoring a deleted version or a file.
+Add a first-class `restore` operation that makes a recoverable object version
+current again. Implement the operation for versioned S3 buckets first.
 
 # Motivation
 
-Cloud storage providers implement data recovery through different mechanisms:
+Storage services retain deleted data through different mechanisms. S3 places a
+delete marker above existing object versions, while other services can expose a
+separate soft-delete lifecycle. OpenDAL users currently need service-specific
+recovery code even when each service can restore the object.
 
-- Example 1: **AWS S3** uses versioning exclusively. Deleted objects become "delete markers" and can be restored by copying a previous version or removing the delete marker.
-- Example 2: **GCS and Azure Blob Storage**  provide both versioning AND soft delete as separate, independent features that can be enabled separately or together.
-
-Currently, there is no standardized way in OpenDAL to restore deleted objects across these different paradigms. This creates challenges for downstream projects that need data recovery capabilities. For example, iceberg-java [already supports file restore](https://github.com/apache/iceberg/blob/main/api/src/main/java/org/apache/iceberg/io/SupportsRecoveryOperations.java) in some cloud environments, while iceberg-rust, written with OpenDAL, does not provide this functionality yet.
-
-In order to secure data pipelines, users currently have to maintain implementations of restore logic across multiple languages and storage backends. Having this functionality in OpenDAL would centralize this capability and make it available to all downstream users.
+A dedicated operation gives applications one recovery contract and lets each
+service implement that contract with its native mechanism. The operation also
+keeps restore-specific capabilities and conditions independent from general
+copy or delete capabilities.
 
 # Guide-level explanation
 
-OpenDAL provides two ways to restore deleted files, depending on the storage backend's capabilities:
-
-1. **Version-based restoration**: Extend the `copy` operation with an optional source `version` parameter to enable promoting non-current versions to the current version (for storage systems with versioning support)
-2. **Soft delete restoration**: Add an `undelete` operation for storage systems that implement soft delete as a distinct feature from versioning (GCS and Azure Blob Storage)
-
-We might also provide a high-level `restore` API that automatically chooses the right approach based on service capabilities, defaulting to versioning approach:
+Use [`crate::Operator::restore`] to restore the latest recoverable state for a
+path:
 
 ```rust
-impl Operator {
-    pub async fn restore(&self, path: &str, version: Option<&str>) -> Result<()> {
-        let cap = self.info().full_capability();
-
-        if let Some(v) = version {
-            // Restore specific version via copy
-            if cap.versioning {
-                return self.copy_with(&path, &path).source_version(&v).await;
-            }
-        } else {
-            // Restore soft-deleted via undelete
-            if cap.undelete {
-                return self.undelete(path).await;
-            }
-
-            // Fall back to latest version via copy
-            if cap.versioning && cap.list_with_versions {
-                let version = self.get_latest_version(path).await?;
-                return self.copy_with(&path, &path).source_version(&version).await;
-            }
-        }
-
-        Err(Error::new(ErrorKind::Unsupported, "restoration not supported"))
-    }
+use opendal_core::{Operator, Result};
+
+async fn restore(op: Operator) -> Result<()> {
+    op.restore("path/to/file").await?;
+    Ok(())
 }
 ```
 
+The operation has these path-level semantics:
 
-## Approach 1: Version-Based Restoration (Copy with Version)
+- It succeeds when the path is already live.
+- It restores the service's latest recoverable deletion state.
+- It returns `ErrorKind::NotFound` when neither a live object nor a recoverable
+  deletion state exists.
+- It returns `ErrorKind::Unsupported` when the service does not implement
+  restoration.
 
-For storage systems with versioning enabled, you can restore a deleted file by copying a previous version:
+Use [`crate::Operator::restore_with`] to promote a specific historical version:
 
 ```rust
-use opendal::{Operator, Result};
-
-async fn restore_via_version(op: Operator) -> Result<()> {
-    // List versions to find the one to restore
-    // let mut lister = op.lister_with("path/to/file.txt")
-    //     .versions(true)
-    //     .await?;
+use opendal_core::{Operator, Result};
 
-    // Pick the version you want to restore
-    let version_id = "version-123";
-
-    // Copy the old version to create a new current version
-    op.copy_with("path/to/file.txt", "path/to/file.txt")
-        .source_version(version_id)
+async fn restore_version(op: Operator, version: &str) -> Result<()> {
+    op.restore_with("path/to/file")
+        .version(version)
         .await?;
-
-    // The file is now restored with content from the specified version
     Ok(())
 }
 ```
 
-## Approach 2: Soft Delete Restoration (Undelete)
+Restoring a version creates a new current version from the selected historical
+version. By default, it can replace the current value at the path.
 
-For storage systems with soft delete enabled, you can restore a soft-deleted file by using a new API endpoint `undelete`:
+Add `if_not_exists(true)` when a recovery workflow must not overwrite an object
+that another writer recreated after the version was selected:
 
 ```rust
-use opendal::{Operator, Result};
+use opendal_core::{Operator, Result};
 
-async fn restore_soft_deleted(op: Operator) -> Result<()> {
-    // Check if the storage backend supports undelete
-    if op.info().full_capability().undelete {
-        // Restore a soft-deleted file
-        op.undelete("path/to/file.txt").await?;
-
-        // The file is now restored to its last alive state
-        let content = op.read("path/to/file.txt").await?;
-    }
+async fn restore_version_if_absent(op: Operator, version: &str) -> Result<()> {
+    op.restore_with("path/to/file")
+        .version(version)
+        .if_not_exists(true)
+        .await?;
     Ok(())
 }
 ```
 
-## Choosing the Right Approach
+`if_not_exists` requires an explicit version. The operation returns
+`ErrorKind::ConfigInvalid` when the option is set without one and
+`ErrorKind::ConditionNotMatch` when the path already exists.
 
-The choice depends on your storage configuration:
+Applications must inspect the effective capabilities before relying on optional
+restore behavior:
 
-```rust
-let cap = operator.info().full_capability();
-
-if cap.undelete {
-    // Use undelete for soft-deleted files
-    operator.undelete("deleted_file.txt").await?;
-} else if cap.versioning {
-    // Use copy with version for versioned storage
-    let version_id = /* get version from listing */;
-    operator.copy_with("deleted_file.txt", "deleted_file.txt")
-        .source_version(version_id)
-        .await?;
-} else {
-    // Backend doesn't support restoration
-    return Err(Error::new(ErrorKind::Unsupported, "restoration not supported"));
-}
-```
-
-## Error Handling
+```rust,ignore
+let capability = op.info().full_capability();
 
-### Copy with Version Errors
-
-```rust
-match op.copy_with("file.txt", "file.txt")
-    .source_version(version_id)
-    .await
-{
-    Ok(_) => println!("Version restored successfully"),
-    Err(e) if e.kind() == ErrorKind::NotFound => {
-        // Source version doesn't exist in history
-        println!("Version {} not found", version_id);
-    }
-    Err(e) if e.kind() == ErrorKind::Unsupported => {
-        println!("Copy with version not supported by this backend");
-    }
-    Err(e) => println!("Copy failed: {}", e),
-}
-```
-
-When copying to a non-existing destination path, the behavior follows the existing `copy` operation semantics (typically succeeds, creating the destination).
-
-### Undelete Errors
-
-```rust
-match op.undelete("file.txt").await {
-    Ok(_) => {
-        // Success: file was restored from soft-deleted state
-        // OR file was already alive (idempotent success)
-        println!("File is now alive");
-    }
-    Err(e) if e.kind() == ErrorKind::NotFound => {
-        // No soft-deleted object with this path exists
-        println!("No soft-deleted file found at this path");
-    }
-    Err(e) if e.kind() == ErrorKind::Unsupported => {
-        println!("Undelete not supported by this backend");
-    }
-    Err(e) => println!("Undelete failed: {}", e),
+if capability.restore_with_version {
+    op.restore_with("path/to/file")
+        .version("version-id")
+        .await?;
 }
 ```
 
-**Important**: `undelete` is idempotent. If the file already exists and is alive, calling `undelete` succeeds (returns `Ok`). This allows for safe retry logic and simplifies recovery workflows.
-
 # Reference-level explanation
 
-## Approach 1: Copy with Source Version
-
-### Extended Copy API
-
-The `OpCopy` operation is extended with an optional source version parameter:
-
-```rust
-#[derive(Debug, Clone, Default)]
-pub struct OpCopy {
-    // ... existing fields
-    source_version: Option<String>,
-}
-
-impl OpCopy {
-    pub fn with_source_version(mut self, version: &str) -> Self {
-        self.source_version = Some(version.to_string());
-        self
-    }
-
-    pub fn source_version(&self) -> Option<&str> {
-        self.source_version.as_deref()
-    }
-}
-```
-
-### Capability Flag
+## Public API
 
-No new capability flag is needed for copy with version. The existing `versioning` capability flag indicates whether the backend supports versioned operations, including copying from specific versions:
+The async operator provides:
 
-```rust
-pub struct Capability {
-    // ... other fields
-    pub versioning: bool, // existing capability
-}
-```
-
-### Public API Extension
-
-```rust
+```rust,ignore
 impl Operator {
-    pub fn copy_with(&self, from: &str) -> FutureCopy {
-        FutureCopy::new(self.clone(), from.to_string())
-    }
-}
-
-pub struct FutureCopy {
-    op: Operator,
-    from: String,
-    source_version: Option<String>,
-}
+    pub async fn restore(&self, path: &str) -> Result<()>;
 
-impl FutureCopy {
-    pub fn source_version(mut self, version: impl Into<String>) -> Self {
-        self.source_version = Some(version.into());
-        self
-    }
+    pub fn restore_with(
+        &self,
+        path: &str,
+    ) -> FutureRestore<impl Future<Output = Result<()>>>;
 
-    pub async fn run(self, to: impl AsRef<str>) -> Result<()> {
-        let from = normalize_path(&self.from);
-        let to = normalize_path(to.as_ref());
-
-        let mut args = OpCopy::new(&from, &to);
-        if let Some(version) = self.source_version {
-            args = args.with_source_version(&version);
-        }
-
-        self.op.inner().copy(&from, &to, args).await?;
-        Ok(())
-    }
+    pub async fn restore_options(
+        &self,
+        path: &str,
+        opts: impl Into<RestoreOptions>,
+    ) -> Result<()>;
 }
 ```
 
-### Operation Contract
-
-The extended `copy` operation with source version has the following contract:
-
-- **Purpose**: Copy content from a specific version of an object to a destination path
-- **Success condition**: Returns `Ok(RpCopy)` when the version is successfully copied to the destination
-- **Error conditions**:
-  - Returns `ErrorKind::NotFound` if the source version doesn't exist in the object's history
-  - Returns `ErrorKind::Unsupported` if the backend doesn't support versioned copy
-  - Other errors follow the existing `copy` operation semantics
-- **Capability requirement**: The `Capability::versioning` flag must be `true` for versioned copy to be available
-- **Destination behavior**: Follows existing `copy` semantics (typically creates destination if it doesn't exist)
-
-### Implementation Pattern
+`FutureRestore` exposes `version` and `if_not_exists` setters. The blocking
+operator provides `restore` and `restore_options` with the same contract.
 
-For backends with versioning support (S3, GCS, Azure), the `copy` implementation checks for the source version:
+`RestoreOptions` contains:
 
 ```rust
-async fn copy(&self, from: &str, to: &str, args: OpCopy) -> Result<RpCopy> {
-    let source_path = if let Some(version) = args.source_version() {
-        // Include version in the source path/query parameters
-        format!("{}?versionId={}", from, version)
-    } else {
-        from.to_string()
-    };
-
-    // Perform copy operation with potentially versioned source
-    // ...
+pub struct RestoreOptions {
+    pub version: Option<String>,
+    pub if_not_exists: bool,
 }
 ```
 
-## Approach 2: Undelete for Soft Delete
+OpenDAL normalizes the path and rejects directory paths before dispatching the
+operation.
 
-### Operation Contract
+## Raw operation
 
-The `undelete` operation is defined in the `Access` trait with the following contract:
+The raw API adds `Operation::Restore`, `OpRestore`, and `RpRestore`.
+`Service::restore` receives the path and `OpRestore`. Services that do not
+support restoration return `ErrorKind::Unsupported`.
 
-- **Purpose**: Restores a soft-deleted object to its active state
-- **Parameters**: Only requires the path - no version/generation parameters needed
-- **Success condition**: Returns `Ok(RpUndelete)` when:
-  - The path was in soft-deleted state and is now restored, OR
-  - The path already exists as an alive object (idempotent success)
-- **Error conditions**:
-  - Returns `ErrorKind::NotFound` if no object (alive or soft-deleted) exists at the path
-  - Returns `ErrorKind::Unsupported` if the backend doesn't support undelete
-- **Capability requirement**: The `Capability::undelete` flag must be `true` for the operation to be available
-- **Idempotency**: Calling `undelete` on an already-alive object succeeds without error
-- **Backend behavior**: Implementations automatically restore the latest soft-deleted version (e.g., GCS internally discovers the generation number)
+`ServiceDyn::restore_dyn` is a required method, matching the other dynamic
+service operations. All layers must either implement restore-specific behavior
+or forward the call to the inner service.
 
-### Core Types
+## Capabilities
 
-**Operation struct** (`OpUndelete`):
-```rust
-#[derive(Debug, Clone, Default)]
-pub struct OpUndelete {}
-```
+`Capability` exposes three restore flags:
 
-**Response struct** (`RpUndelete`):
-```rust
-#[derive(Debug, Clone, Default)]
-pub struct RpUndelete {}
-```
-
-**Capability flag**:
 ```rust
 pub struct Capability {
-    // ... other fields
-    pub undelete: bool,
-}
-```
-
-### Trait Definition
-
-The `Access` trait is extended with:
-
-```rust
-fn undelete(
-    &self,
-    path: &str,
-    args: OpUndelete,
-) -> impl Future<Output = Result<RpUndelete>> + MaybeSend {
-    let (_, _) = (path, args);
-    ready(Err(Error::new(
-        ErrorKind::Unsupported,
-        "operation is not supported",
-    )))
-}
-```
-
-### Public API
-
-Users access the functionality through:
-
-```rust
-impl Operator {
-    pub async fn undelete(&self, path: &str) -> Result<()> {
-        let path = normalize_path(path);
-        self.inner().undelete(&path, OpUndelete::new()).await?;
-        Ok(())
-    }
-}
-```
-
-## Layer Integration
-
-Both operations integrate with OpenDAL's layer system. The following layers provide explicit implementations:
-
-1. **RetryLayer**: Wraps calls with retry logic for temporary failures
-2. **TimeoutLayer**: Adds timeout protection
-3. **LoggingLayer**: Logs operation start, finish, and errors
-4. **ConcurrentLimitLayer**: Applies semaphore-based concurrency limits
-
-Other layers rely on default forwarding through `LayeredAccess`, which delegates to the inner layer.
-
-## Implementation Details
-
-### AWS S3
-
-AWS S3 provides [soft delete through versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/versioning-workflows.html) and delete markers. Recovery is achieved by copying a previous version to the same path.
-
-S3 does not implement `undelete` as it has no separate soft delete feature.
-
-### Google Cloud Storage
-
-GCS provides both [soft delete with retention policies](https://cloud.google.com/storage/docs/soft-delete) and [object versioning](https://cloud.google.com/storage/docs/object-versioning).
-
-**For soft delete**, implement `undelete` using the [GCS restore API](https://cloud.google.com/storage/docs/use-soft-deleted-objects#restore):
-
-```rust
-pub async fn gcs_undelete_object(&self, path: &str) -> Result<Response<Buffer>> {
-    // Step 1: List soft-deleted objects to find the generation number
-    let list_url = format!(
-        "https://storage.googleapis.com/storage/v1/b/{}/o?prefix={}&softDeleted=true",
-        self.bucket,
-        percent_encode_path(path)
-    );
-
-    let list_req = Request::get(&list_url)
-        .header(AUTHORIZATION, format!("Bearer {}", self.token()?))
-        .body(Buffer::new())
-        .map_err(new_request_build_error)?;
-
-    let list_resp = self.send(list_req).await?;
-
-    // Parse response to extract the latest generation number
-    // (In practice, parse JSON and find the matching object's generation)
-    let generation = parse_latest_generation(list_resp, path)?;
-
-    // Step 2: Restore using the generation number
-    let restore_url = format!(
-        "https://storage.googleapis.com/storage/v1/b/{}/o/{}/restore?generation={}",
-        self.bucket,
-        percent_encode_path(path),
-        generation
-    );
-
-    let restore_req = Request::post(&restore_url)
-        .header(AUTHORIZATION, format!("Bearer {}", self.token()?))
-        .header(CONTENT_TYPE, "application/json")
-        .extension(Operation::Undelete)
-        .body(Buffer::new())
-        .map_err(new_request_build_error)?;
-
-    self.send(restore_req).await
+    pub restore: bool,
+    pub restore_with_version: bool,
+    pub restore_with_if_not_exists: bool,
 }
 ```
 
-This implementation:
-1. Lists soft-deleted objects at the path prefix
-2. Extracts the latest generation number from the response
-3. Calls the restore API with that generation
-4. Keeps the public API simple (no generation parameter needed)
-
-Capability:
-```rust
-undelete: self.config.enable_soft_deletes,
-versioning: self.config.enable_versioning, // existing capability
-```
-
-**For versioning**, extend the existing `copy` implementation to support source version parameter.
-
-### Azure Blob Storage
-
-Azure provides both [soft delete with retention policies](https://learn.microsoft.com/en-us/rest/api/storageservices/soft-delete-for-blob-storage) and [object versioning](https://learn.microsoft.com/en-us/azure/storage/blobs/versioning-overview).
-
-**For soft delete**, use the [Undelete Blob REST API](https://learn.microsoft.com/en-us/rest/api/storageservices/undelete-blob):
-
-```rust
-pub async fn azblob_undelete_blob(&self, path: &str) -> Result<Response<Buffer>> {
-    let url = format!("{}?comp=undelete", self.build_path_url(path));
-
-    let mut req = Request::put(&url)
-        .header(CONTENT_LENGTH, 0)
-        .extension(Operation::Undelete)
-        .body(Buffer::new())
-        .map_err(new_request_build_error)?;
-
-    self.sign(&mut req).await?;
-    self.send(req).await
-}
-```
-
-**For versioning**, extend the existing `copy` implementation:
-
-```rust
-pub async fn azblob_copy_blob(&self, from: &str, to: &str, version: Option<&str>) -> Result<Response<Buffer>> {
-    let source_url = if let Some(v) = version {
-        format!("{}?versionid={}", self.build_path_url(from), v)
-    } else {
-        self.build_path_url(from)
-    };
-
-    let url = self.build_path_url(to);
-
-    let mut req = Request::put(&url)
-        .header("x-ms-copy-source", source_url)
-        .extension(Operation::Copy)
-        .body(Buffer::new())
-        .map_err(new_request_build_error)?;
-
-    self.sign(&mut req).await?;
-    self.send(req).await
-}
-```
-
-Capabilities:
-```rust
-undelete: self.config.enable_soft_deletes,
-versioning: self.config.enable_versioning, // existing capability
-```
-
-## Corner Cases
-
-### When to Use Which Approach
-
-| Storage Backend | Soft Delete Available | Versioning Available | Recommended Approach |
-|-----------------|----------------------|----------------------|----------------------|
-| AWS S3 | No (uses versioning) | Yes | Copy with version |
-| GCS | Yes | Yes | Either (based on configuration) |
-| Azure Blob | Yes | Yes | Either (based on configuration) |
-
-### Soft Delete vs Versioning in GCS/Azure
-
-In GCS and Azure Blob Storage, soft delete and versioning are independent:
+- `restore` indicates support for the base operation.
+- `restore_with_version` indicates support for selecting a historical version.
+- `restore_with_if_not_exists` indicates support for conditional version
+  promotion.
 
-- **Soft delete**: When enabled, deleted objects are marked as soft-deleted and retained for a configured period. They can be restored using `undelete` which brings back the last alive state.
-- **Versioning**: When enabled, every modification creates a new version. Deleted objects create a delete marker or a special version. Restoration requires identifying a specific version and copying it.
+The correctness and capability-check layers reject unsupported restore options
+before dispatch. Capability override and simulation layers can independently
+disable each flag.
 
-You can enable both simultaneously in GCS. In this case:
-- Use `undelete` for simple restoration of recently deleted files (simpler, no need to find version ID)
-- Use `copy` with version for restoring specific historical versions or when soft delete retention has expired
+## S3 implementation
 
-Enabling both features in Azblob in some configurations is impossible.
+S3 restoration requires bucket versioning.
 
-### Backend-Specific Undelete Implementation
+For `restore(path)`, the S3 service requests the first entry from
+`ListObjectVersions` for the exact object key:
 
-While the public API for `undelete` is consistent across backends (just provide the path), the internal implementation differs:
+1. If the current entry is a live version, the operation succeeds without a
+   write.
+2. If the current entry is a delete marker, the service deletes that marker by
+   version ID and succeeds.
+3. If neither entry exists for the exact key, the operation returns
+   `ErrorKind::NotFound`.
 
-**Azure Blob Storage**:
-- Single API call: `PUT {blob-url}?comp=undelete`
-- Automatically restores the most recent soft-deleted version
-- Simple and fast
+Each service call removes at most one current delete marker. It does not scan or
+delete older marker versions. This keeps one restore call mapped to one S3
+delete-marker operation and leaves version-history policy to the caller. S3 can
+[stack delete markers](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManagingDelMarkers.html),
+so callers can issue another restore operation when they intend to remove the
+next marker.
 
-**Google Cloud Storage**:
-- Two API calls internally:
-  1. `GET /b/{bucket}/o?prefix={path}&softDeleted=true` - List soft-deleted objects
-  2. `POST /b/{bucket}/o/{path}/restore?generation={generation}` - Restore with generation number
-- The implementation automatically discovers the latest generation before restoring
-- Additional latency due to the extra list call, but maintains a simple public API
+For `restore_with(path).version(version)`, the S3 service issues a server-side
+copy from that version to the same key. The copy creates a new current version.
+When `if_not_exists` is set, the service applies the destination
+`If-None-Match: *` condition to the copy request.
 
-Both backends present the same simple interface to users: `op.undelete(path)`, with the complexity hidden inside the implementation.
+S3 Express directory buckets do not support object versioning, so they expose
+all restore capabilities as `false`.
 
-### Idempotent Undelete
+## Error and retry behavior
 
-Calling `undelete` on a file that already exists and is alive **succeeds** without error. This idempotent behavior:
-- Simplifies recovery workflows (no need to check if file is alive first)
-- Enables safe retry logic
-- Makes the operation predictable: "ensure this path is alive" rather than "restore from deleted state"
-
-Example: Azure Blob Storage's Undelete Blob API exhibits this behavior - calling undelete on an already-active blob succeeds.
-
-### No Object at Path
-
-Calling `undelete` on a path where no object exists (neither alive nor soft-deleted) returns `NotFound` error.
-
-### Expired Retention Period
-
-If the soft delete retention period has expired, the blob is permanently deleted and `undelete` will return `NotFound`. In this case, if versioning is also enabled, you may still be able to restore using `copy` with version.
-
-### Copy with Non-existent Version
-
-When using `copy` with source version, if the specified version doesn't exist in the object's history, the operation returns `NotFound`.
-
-### Copy to Non-existent Path
-
-When using `copy` with version to a destination path, the behavior follows the existing `copy` operation semantics (typically succeeds, creating the destination object).
+Restore errors carry `Operation::Restore` context. Observability layers record
+restore as a distinct operation. Retry and timeout layers apply their existing
+operation policies to restore calls.
 
 # Drawbacks
 
-- **Two different APIs**: Users need to understand when to use `copy` with version vs `undelete`
-- **Backend-specific behavior**: Not all storage backends support both approaches
-- **Testing complexity**: Requires both soft delete and versioning configuration in storage backends for comprehensive integration testing
+- A path-only restore maps to different native mechanisms across services.
+- Services need explicit restore capability declarations even when their
+  implementation reuses copy or delete requests.
+- S3 path-only restore performs a list request before deleting a marker.
+- One call removes only the current S3 delete marker; applications that manage
+  older marker history must do so explicitly.
 
 # Rationale and alternatives
 
-## Why This Design
-
-This design was chosen because:
-
-1. **Aligns with cloud provider architecture**: Respects the distinction between soft delete and versioning that GCS and Azure make explicit
-2. **Reuses existing API where appropriate**: Extending `copy` for version-based restoration is intuitive and consistent with the "copy from source" mental model
-3. **Clear separation of concerns**: `undelete` is specifically for soft delete scenarios, while `copy` with version is for version-based scenarios
-4. **Backend flexibility**: Each backend can implement the approach(es) that match its native capabilities
-5. **User choice**: For backends supporting both (GCS/Azure), users can choose the simpler approach (undelete) or the more granular approach (copy with version)
-6. **Simple public API**: The `undelete` operation requires only a path parameter across all backends. Backend-specific details (like GCS generation discovery) are handled internally, keeping the API consistent and easy to use
-
-## Alternative 1: Undelete with Optional Version Parameter
-
-**Description**: Have a single `undelete` API that accepts an optional version parameter.
-
-**Pros**:
-- Single API for all restoration scenarios
-- Simpler mental model
-
-**Cons**:
-- **Copying a version to another path will remain unimplemented**: if one wants to create a new alive object "fileA-version123-backup" from another object's ("fileA") version, it would require restoring this version as "fileA" and then copying it into "fileA-version123-backup" destination; this would become even more complicated if "fileA" is alive all this time.
-- **Less discoverable**: Users familiar with copy operations might not think to look at undelete for version restoration
-
-## Alternative 2: Promote API
-
-**Description**: Add a new `promote(path, version)` API for version-based restoration.
-
-**Pros**:
-- Explicit naming for version promotion
-- Clear separation from undelete
-
-**Cons**:
-- **New operation**: Adds a third operation when `copy` already exists and conceptually fits
-- **Limited use case**: Only works for versioning, not soft delete
-- **Less intuitive**: "Promote" is less clear than "copy from version"
+## Extend copy with a source version
 
-## Alternative 3: Undelete Only
+Versioned copy can promote a historical S3 version, but it does not express
+path-level recovery when the caller has no version ID. It also makes recovery
+capabilities depend on the broader copy contract. A first-class restore
+operation supports both path-level and version-selected workflows.
 
-**Description**: Only implement `undelete` and try to make it work for all backends.
+## Add a separate undelete operation
 
-**Cons**:
-- **Doesn't match S3's model**: S3 has no soft delete concept, forcing undelete to be implemented via versioning feels artificial
-- **Less explicit**: Users don't know if they're restoring from soft delete or versioning
-- **Harder to implement**: Backends would need to check multiple features internally and choose restoration strategy
+`undelete` matches the terminology of some soft-delete APIs but does not match
+S3's versioning model. `restore` describes the user outcome without exposing the
+provider's retention mechanism.
 
-## Impact of Not Implementing
+## Remove every S3 delete marker
 
-Without this feature:
-- Downstream projects cannot provide data recovery features
-- Data recovery workflows remain fragmented across different OpenDAL users
-- The versioning feature remains incomplete without a clear restoration path
-
-# Prior art
-
-## AWS S3
-
-AWS S3 provides [soft delete through versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjectVersions.html) and delete markers. Recovery is achieved by:
-- Listing object versions
-- Copying a previous version to create a new current version
-- OR removing all delete markers stacked on top of the latest version (no plans to use this approach in OpenDAL)
-
-## Azure Blob Storage
-
-Azure provides:
-- Explicit [Undelete Blob](https://learn.microsoft.com/en-us/rest/api/storageservices/undelete-blob) REST API for soft delete
-- [Blob versioning](https://learn.microsoft.com/en-us/azure/storage/blobs/versioning-overview) as a separate feature
-- [Copy Blob](https://learn.microsoft.com/en-us/rest/api/storageservices/copy-blob) operation that supports copying from specific versions
-
-## Google Cloud Storage
-
-GCS provides:
-- [Soft delete with retention policies](https://cloud.google.com/storage/docs/soft-delete), allowing recovery within the retention window
-- [Object versioning](https://cloud.google.com/storage/docs/object-versioning) as a separate feature
-- APIs to list soft-deleted objects and restore them
-
-# Unresolved questions
-
-- Should `copy` with source version support copying from soft-deleted versions in GCS/Azure? (e.g., combining both features)
-- Should we add a helper method that automatically chooses between undelete and copy-with-version based on available capabilities?
+Scanning and removing historical markers makes one restore call perform an
+unbounded number of irreversible version-history changes. The chosen contract
+operates on the current marker once per call.
 
 # Future possibilities
 
-## Batch Operations
-
-Add batch operations for both approaches. Example:
-
-```rust
-// Batch undelete
-op.undelete_iter(vec!["file1.txt", "file2.txt"]).await?;
-```
-
-## List Deleted Files
-
-Extend capability to list soft-deleted files to all backends that support soft deletion:
-
-```rust
-let mut lister = op.lister_with("path/")
-    .deleted(true)  // Include soft-deleted files
-    .await?;
-```
+- Implement restore for services with native soft-delete APIs.
+- Implement version-selected restore for other versioned services.
+- Add batch restore after individual service contracts are established.
diff --git a/core/core/src/layers/capability_override.rs b/core/core/src/layers/capability_override.rs
index d7bf63317..9501dbaac 100644
--- a/core/core/src/layers/capability_override.rs
+++ b/core/core/src/layers/capability_override.rs
@@ -178,6 +178,15 @@ impl Service for CapabilityOverrideService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/core/src/layers/complete.rs b/core/core/src/layers/complete.rs
index a2c84e160..e71ceb553 100644
--- a/core/core/src/layers/complete.rs
+++ b/core/core/src/layers/complete.rs
@@ -111,6 +111,15 @@ impl Service for CompleteService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.inner.stat(ctx, path, args).await
     }
diff --git a/core/core/src/layers/correctness_check.rs b/core/core/src/layers/correctness_check.rs
index 603cfd75c..e9ac92004 100644
--- a/core/core/src/layers/correctness_check.rs
+++ b/core/core/src/layers/correctness_check.rs
@@ -261,6 +261,38 @@ impl Service for CorrectnessService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let capability = self.capability();
+        let scheme = self.info().scheme();
+        if !capability.restore {
+            return Err(new_unsupported_error(scheme, Operation::Restore, ""));
+        }
+        if args.version().is_some() && !capability.restore_with_version {
+            return Err(new_unsupported_error(scheme, Operation::Restore, "version"));
+        }
+        if args.if_not_exists() && !capability.restore_with_if_not_exists {
+            return Err(new_unsupported_error(
+                scheme,
+                Operation::Restore,
+                "if_not_exists",
+            ));
+        }
+        if args.if_not_exists() && args.version().is_none() {
+            return Err(Error::new(
+                ErrorKind::ConfigInvalid,
+                "if_not_exists requires a restore version",
+            )
+            .with_operation(Operation::Restore));
+        }
+
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/core/src/layers/error_context.rs b/core/core/src/layers/error_context.rs
index 761112816..a84758300 100644
--- a/core/core/src/layers/error_context.rs
+++ b/core/core/src/layers/error_context.rs
@@ -154,6 +154,19 @@ impl Service for ErrorContextService {
         })
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await.map_err(|err| {
+            err.with_operation(Operation::Restore)
+                .with_context("service", self.info().scheme())
+                .with_context("path", path)
+        })
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.inner.stat(ctx, path, args).await.map_err(|err| {
             err.with_operation(Operation::Stat)
diff --git a/core/core/src/layers/simulate.rs b/core/core/src/layers/simulate.rs
index 3d22a873d..7ac1a0a8d 100644
--- a/core/core/src/layers/simulate.rs
+++ b/core/core/src/layers/simulate.rs
@@ -345,6 +345,15 @@ impl Service for SimulateService {
         self.srv.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.srv.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.simulate_stat(ctx, path, args).await
     }
diff --git a/core/core/src/raw/accessor.rs b/core/core/src/raw/accessor.rs
index 0036af785..6902daa5d 100644
--- a/core/core/src/raw/accessor.rs
+++ b/core/core/src/raw/accessor.rs
@@ -230,6 +230,27 @@ pub trait Service: Send + Sync + Debug + Unpin + 'static {
         args: OpRename,
     ) -> impl Future<Output = Result<RpRename>> + MaybeSend;
 
+    /// Invoke the `restore` operation on the specified path.
+    ///
+    /// Requires [`Capability::restore`].
+    ///
+    /// # Behavior
+    ///
+    /// - `path` is a normalized file path.
+    /// - Without a version, restore reverses the latest recoverable deletion state.
+    /// - With a version, restore promotes that historical version to the current version.
+    fn restore(
+        &self,
+        _ctx: &OperationContext,
+        _path: &str,
+        _args: OpRestore,
+    ) -> impl Future<Output = Result<RpRestore>> + MaybeSend {
+        std::future::ready(Err(Error::new(
+            ErrorKind::Unsupported,
+            "operation is not supported",
+        )))
+    }
+
     /// Invoke the `presign` operation on the specified path.
     ///
     /// Requires [`Capability::presign`] and the matching presign operation
@@ -312,6 +333,14 @@ pub trait ServiceDyn: Send + Sync + Debug + Unpin + 'static {
         args: OpRename,
     ) -> BoxedFuture<'a, Result<RpRename>>;
 
+    /// Dyn version of [`Service::restore`].
+    fn restore_dyn<'a>(
+        &'a self,
+        ctx: &'a OperationContext,
+        path: &'a str,
+        args: OpRestore,
+    ) -> BoxedFuture<'a, Result<RpRestore>>;
+
     /// Dyn version of [`Service::presign`].
     fn presign_dyn<'a>(
         &'a self,
@@ -403,6 +432,15 @@ impl<S: Service + ?Sized> ServiceDyn for S {
         Box::pin(self.rename(ctx, from, to, args))
     }
 
+    fn restore_dyn<'a>(
+        &'a self,
+        ctx: &'a OperationContext,
+        path: &'a str,
+        args: OpRestore,
+    ) -> BoxedFuture<'a, Result<RpRestore>> {
+        Box::pin(self.restore(ctx, path, args))
+    }
+
     fn presign_dyn<'a>(
         &'a self,
         ctx: &'a OperationContext,
@@ -479,6 +517,15 @@ impl<T: ServiceDyn + ?Sized> Service for Arc<T> {
         self.as_ref().rename_dyn(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.as_ref().restore_dyn(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/core/src/raw/operation.rs b/core/core/src/raw/operation.rs
index 28b039b8b..421899684 100644
--- a/core/core/src/raw/operation.rs
+++ b/core/core/src/raw/operation.rs
@@ -41,6 +41,8 @@ pub enum Operation {
     Copy,
     /// Operation to rename a file.
     Rename,
+    /// Operation to restore a file.
+    Restore,
     /// Operation to stat a file or a directory.
     Stat,
     /// Operation to delete files.
@@ -73,6 +75,7 @@ impl From<Operation> for &'static str {
             Operation::Write => "write",
             Operation::Copy => "copy",
             Operation::Rename => "rename",
+            Operation::Restore => "restore",
             Operation::Stat => "stat",
             Operation::Delete => "delete",
             Operation::List => "list",
diff --git a/core/core/src/raw/ops.rs b/core/core/src/raw/ops.rs
index 7f32031c6..6b3cc53bb 100644
--- a/core/core/src/raw/ops.rs
+++ b/core/core/src/raw/ops.rs
@@ -1058,3 +1058,48 @@ impl From<options::RenameOptions> for OpRename {
         }
     }
 }
+
+/// Arguments for `restore` operation.
+#[derive(Debug, Clone, Default)]
+pub struct OpRestore {
+    version: Option<String>,
+    if_not_exists: bool,
+}
+
+impl OpRestore {
+    /// Create a new `OpRestore`.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Set the version to restore.
+    pub fn with_version(mut self, version: impl Into<String>) -> Self {
+        self.version = Some(version.into());
+        self
+    }
+
+    /// Return the version to restore.
+    pub fn version(&self) -> Option<&str> {
+        self.version.as_deref()
+    }
+
+    /// Set whether the restore should fail if the path currently exists.
+    pub fn with_if_not_exists(mut self, if_not_exists: bool) -> Self {
+        self.if_not_exists = if_not_exists;
+        self
+    }
+
+    /// Return whether the restore should fail if the path currently exists.
+    pub fn if_not_exists(&self) -> bool {
+        self.if_not_exists
+    }
+}
+
+impl From<options::RestoreOptions> for OpRestore {
+    fn from(value: options::RestoreOptions) -> Self {
+        Self {
+            version: value.version,
+            if_not_exists: value.if_not_exists,
+        }
+    }
+}
diff --git a/core/core/src/raw/rps.rs b/core/core/src/raw/rps.rs
index 3462113df..936ff2c38 100644
--- a/core/core/src/raw/rps.rs
+++ b/core/core/src/raw/rps.rs
@@ -183,6 +183,17 @@ impl RpRename {
     }
 }
 
+/// Reply for `restore` operation.
+#[derive(Debug, Clone, Default)]
+pub struct RpRestore {}
+
+impl RpRestore {
+    /// Create a new reply for `restore`.
+    pub fn new() -> Self {
+        Self {}
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use anyhow::Result;
diff --git a/core/core/src/types/capability.rs b/core/core/src/types/capability.rs
index cca00a6e1..43ff7432a 100644
--- a/core/core/src/types/capability.rs
+++ b/core/core/src/types/capability.rs
@@ -164,6 +164,13 @@ pub struct Capability {
     /// Minimum size required for segmented copy tasks.
     pub copy_multi_min_size: Option<usize>,
 
+    /// Indicates if restore operations are supported.
+    pub restore: bool,
+    /// Indicates if restoring a specific version is supported.
+    pub restore_with_version: bool,
+    /// Indicates if conditional restore operations using if-not-exists are supported.
+    pub restore_with_if_not_exists: bool,
+
     /// Indicates if rename operations are supported.
     pub rename: bool,
     /// Indicates if conditional rename operations with if-not-exists are supported.
diff --git a/core/core/src/types/operator/operator.rs b/core/core/src/types/operator/operator.rs
index c27efafb1..3f6961eb0 100644
--- a/core/core/src/types/operator/operator.rs
+++ b/core/core/src/types/operator/operator.rs
@@ -1547,6 +1547,94 @@ impl Operator {
         Ok(())
     }
 
+    /// Restore the given path from its latest deleted state.
+    ///
+    /// Calling `restore` on an already-live path succeeds. Calling it when no
+    /// live object or recoverable deletion state exists returns
+    /// [`ErrorKind::NotFound`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use opendal_core::Operator;
+    /// # use opendal_core::Result;
+    /// # async fn test(op: Operator) -> Result<()> {
+    /// op.restore("path/to/file").await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn restore(&self, path: &str) -> Result<()> {
+        self.restore_with(path).await
+    }
+
+    /// Restore the given path with additional options.
+    ///
+    /// # Examples
+    ///
+    /// Restore a specific version only if the path has not been recreated:
+    ///
+    /// ```
+    /// # use opendal_core::Operator;
+    /// # use opendal_core::Result;
+    /// # async fn test(op: Operator, version: &str) -> Result<()> {
+    /// op.restore_with("path/to/file")
+    ///     .version(version)
+    ///     .if_not_exists(true)
+    ///     .await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn restore_with(&self, path: &str) -> FutureRestore<impl Future<Output = Result<()>>> {
+        let path = normalize_path(path);
+
+        OperatorFuture::new(
+            self.context().clone(),
+            self.service().clone(),
+            path,
+            options::RestoreOptions::default(),
+            Self::restore_inner,
+        )
+    }
+
+    /// Restore the given path with additional options.
+    pub async fn restore_options(
+        &self,
+        path: &str,
+        opts: impl Into<options::RestoreOptions>,
+    ) -> Result<()> {
+        let path = normalize_path(path);
+        let opts = opts.into();
+
+        Self::restore_inner(self.context().clone(), self.service().clone(), path, opts).await
+    }
+
+    async fn restore_inner(
+        ctx: OperationContext,
+        srv: Servicer,
+        path: String,
+        opts: options::RestoreOptions,
+    ) -> Result<()> {
+        if !validate_path(&path, EntryMode::FILE) {
+            return Err(Error::new(ErrorKind::IsADirectory, "path is a directory")
+                .with_operation(Operation::Restore)
+                .with_context("service", srv.info().scheme())
+                .with_context("path", path));
+        }
+
+        if opts.if_not_exists && opts.version.is_none() {
+            return Err(Error::new(
+                ErrorKind::ConfigInvalid,
+                "if_not_exists requires a restore version",
+            )
+            .with_operation(Operation::Restore)
+            .with_context("service", srv.info().scheme())
+            .with_context("path", path));
+        }
+
+        srv.restore(&ctx, &path, opts.into()).await?;
+        Ok(())
+    }
+
     /// Delete the given path.
     ///
     /// # Notes
diff --git a/core/core/src/types/operator/operator_futures.rs b/core/core/src/types/operator/operator_futures.rs
index b8b6c42f5..c92c2b01f 100644
--- a/core/core/src/types/operator/operator_futures.rs
+++ b/core/core/src/types/operator/operator_futures.rs
@@ -1574,3 +1574,22 @@ impl<F: Future<Output = Result<()>>> FutureRename<F> {
         self
     }
 }
+
+/// [`Operator::restore_with`] returns this future.
+///
+/// Use its methods to configure the operation before awaiting it.
+pub type FutureRestore<F> = OperatorFuture<options::RestoreOptions, (), F>;
+
+impl<F: Future<Output = Result<()>>> FutureRestore<F> {
+    /// Restore the specified historical version as the current version.
+    pub fn version(mut self, version: impl Into<String>) -> Self {
+        self.args.version = Some(version.into());
+        self
+    }
+
+    /// Restore the selected version only if the path does not currently exist.
+    pub fn if_not_exists(mut self, if_not_exists: bool) -> Self {
+        self.args.if_not_exists = if_not_exists;
+        self
+    }
+}
diff --git a/core/core/src/types/options.rs b/core/core/src/types/options.rs
index 15c8aa329..7569312d1 100644
--- a/core/core/src/types/options.rs
+++ b/core/core/src/types/options.rs
@@ -643,3 +643,26 @@ pub struct RenameOptions {
     ///   [`crate::ErrorKind::Unsupported`].
     pub if_not_exists: bool,
 }
+
+/// Options for restore operations.
+#[derive(Debug, Clone, Default, Eq, PartialEq)]
+pub struct RestoreOptions {
+    /// Restore a specific historical version as the current version.
+    ///
+    /// ### Capability
+    ///
+    /// Check [`crate::Capability::restore_with_version`] before using this feature.
+    pub version: Option<String>,
+
+    /// Restore the selected version only if the path does not currently exist.
+    ///
+    /// This option requires [`RestoreOptions::version`] to be set. It protects
+    /// recovery workflows from overwriting an object recreated after the version
+    /// to restore was selected.
+    ///
+    /// ### Capability
+    ///
+    /// Check [`crate::Capability::restore_with_if_not_exists`] before using this
+    /// feature.
+    pub if_not_exists: bool,
+}
diff --git a/core/layers/async-backtrace/src/lib.rs b/core/layers/async-backtrace/src/lib.rs
index 7e6e6c7f3..023e6be7f 100644
--- a/core/layers/async-backtrace/src/lib.rs
+++ b/core/layers/async-backtrace/src/lib.rs
@@ -134,6 +134,16 @@ impl Service for AsyncBacktraceAccessor {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    #[async_backtrace::framed]
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     #[async_backtrace::framed]
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.inner.stat(ctx, path, args).await
diff --git a/core/layers/await-tree/src/lib.rs b/core/layers/await-tree/src/lib.rs
index 8f2fc6e5d..408f31845 100644
--- a/core/layers/await-tree/src/lib.rs
+++ b/core/layers/await-tree/src/lib.rs
@@ -137,6 +137,18 @@ impl Service for AwaitTreeAccessor {
             .await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner
+            .restore(ctx, path, args)
+            .instrument_await(format!("opendal::{}", Operation::Restore))
+            .await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.inner
             .stat(ctx, path, args)
diff --git a/core/layers/capability-check/src/lib.rs b/core/layers/capability-check/src/lib.rs
index 784051dc9..28e6a30a4 100644
--- a/core/layers/capability-check/src/lib.rs
+++ b/core/layers/capability-check/src/lib.rs
@@ -209,6 +209,31 @@ impl Service for CapabilityCheckService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let capability = self.capability();
+        let info = self.info();
+        if !capability.restore {
+            return Err(new_unsupported_error(&info, Operation::Restore, ""));
+        }
+        if args.version().is_some() && !capability.restore_with_version {
+            return Err(new_unsupported_error(&info, Operation::Restore, "version"));
+        }
+        if args.if_not_exists() && !capability.restore_with_if_not_exists {
+            return Err(new_unsupported_error(
+                &info,
+                Operation::Restore,
+                "if_not_exists",
+            ));
+        }
+
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/layers/chaos/src/lib.rs b/core/layers/chaos/src/lib.rs
index 0e9ca5201..2051d1f65 100644
--- a/core/layers/chaos/src/lib.rs
+++ b/core/layers/chaos/src/lib.rs
@@ -173,6 +173,15 @@ impl Service for ChaosService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/layers/concurrent-limit/src/lib.rs b/core/layers/concurrent-limit/src/lib.rs
index c539317e9..8734aa9df 100644
--- a/core/layers/concurrent-limit/src/lib.rs
+++ b/core/layers/concurrent-limit/src/lib.rs
@@ -310,6 +310,16 @@ where
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let _permit = self.semaphore.acquire().await;
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let _permit = self.semaphore.acquire().await;
         self.inner.stat(ctx, path, args).await
diff --git a/core/layers/dtrace/src/lib.rs b/core/layers/dtrace/src/lib.rs
index 97def1880..a48a87c70 100644
--- a/core/layers/dtrace/src/lib.rs
+++ b/core/layers/dtrace/src/lib.rs
@@ -229,6 +229,15 @@ impl Service for DTraceService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let c_path = CString::new(path).unwrap();
         probe_lazy!(opendal, stat_start, c_path.as_ptr());
diff --git a/core/layers/fastrace/src/lib.rs b/core/layers/fastrace/src/lib.rs
index eea5a8dea..e4438e89a 100644
--- a/core/layers/fastrace/src/lib.rs
+++ b/core/layers/fastrace/src/lib.rs
@@ -208,6 +208,16 @@ impl Service for FastraceAccessor {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let _guard = Span::enter_with_local_parent(Operation::Restore.into_static());
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let _guard = Span::enter_with_local_parent(Operation::Stat.into_static());
         self.inner.stat(ctx, path, args).await
diff --git a/core/layers/foyer/src/lib.rs b/core/layers/foyer/src/lib.rs
index c78af3623..68880b5e3 100644
--- a/core/layers/foyer/src/lib.rs
+++ b/core/layers/foyer/src/lib.rs
@@ -279,7 +279,11 @@ impl Service for FoyerService {
     }
 
     fn capability(&self) -> Capability {
-        self.inner.capability()
+        let mut capability = self.inner.capability();
+        capability.restore = false;
+        capability.restore_with_version = false;
+        capability.restore_with_if_not_exists = false;
+        capability
     }
 
     fn read(&self, ctx: &OperationContext, path: &str, args: OpRead) -> Result<Self::Reader> {
@@ -343,6 +347,18 @@ impl Service for FoyerService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        _ctx: &OperationContext,
+        _path: &str,
+        _args: OpRestore,
+    ) -> Result<RpRestore> {
+        Err(
+            Error::new(ErrorKind::Unsupported, "operation is not supported")
+                .with_operation(Operation::Restore),
+        )
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
@@ -483,6 +499,9 @@ mod tests {
             Capability {
                 read: true,
                 stat: true,
+                restore: true,
+                restore_with_version: true,
+                restore_with_if_not_exists: true,
                 ..Default::default()
             }
         }
@@ -572,6 +591,25 @@ mod tests {
         OperationContext::new()
     }
 
+    #[tokio::test]
+    async fn test_restore_is_not_supported() {
+        let cache = memory_cache().await;
+        let source = Arc::new(MockReadService::new("0123456789"));
+        assert!(source.capability().restore);
+
+        let service = FoyerLayer::new(cache).apply_service(source);
+        let capability = service.capability();
+        assert!(!capability.restore);
+        assert!(!capability.restore_with_version);
+        assert!(!capability.restore_with_if_not_exists);
+
+        let err = service
+            .restore(&OperationContext::new(), "test", OpRestore::new())
+            .await
+            .expect_err("FoyerLayer must reject restore operations");
+        assert_eq!(err.kind(), ErrorKind::Unsupported);
+    }
+
     #[tokio::test]
     async fn test_full_reader_open_fallback_preserves_stream() {
         let cache = memory_cache().await;
diff --git a/core/layers/hotpath/src/lib.rs b/core/layers/hotpath/src/lib.rs
index a7cfb6c80..f0b779036 100644
--- a/core/layers/hotpath/src/lib.rs
+++ b/core/layers/hotpath/src/lib.rs
@@ -32,6 +32,7 @@ use opendal_core::*;
 const LABEL_CREATE_DIR: &str = "opendal.create_dir";
 const LABEL_READ: &str = "opendal.read";
 const LABEL_RENAME: &str = "opendal.rename";
+const LABEL_RESTORE: &str = "opendal.restore";
 const LABEL_STAT: &str = "opendal.stat";
 const LABEL_PRESIGN: &str = "opendal.presign";
 
@@ -165,6 +166,15 @@ impl Service for HotpathAccessor {
         hotpath::measure_async(LABEL_RENAME, self.inner.rename(ctx, from, to, args)).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        hotpath::measure_async(LABEL_RESTORE, self.inner.restore(ctx, path, args)).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         hotpath::measure_async(LABEL_STAT, self.inner.stat(ctx, path, args)).await
     }
diff --git a/core/layers/immutable-index/src/lib.rs b/core/layers/immutable-index/src/lib.rs
index 070262a8b..a111eb69f 100644
--- a/core/layers/immutable-index/src/lib.rs
+++ b/core/layers/immutable-index/src/lib.rs
@@ -228,6 +228,15 @@ impl Service for ImmutableIndexService {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
diff --git a/core/layers/logging/src/lib.rs b/core/layers/logging/src/lib.rs
index baa43d3b2..9e228cd37 100644
--- a/core/layers/logging/src/lib.rs
+++ b/core/layers/logging/src/lib.rs
@@ -413,6 +413,18 @@ impl<I: LoggingInterceptor> Service for LoggingService<I> {
         result
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.log_start(Operation::Restore, &[("path", path)]);
+        let result = self.inner.restore(ctx, path, args).await;
+        self.log_finish(Operation::Restore, &[("path", path)], result.as_ref().err());
+        result
+    }
+
     fn list(&self, ctx: &OperationContext, path: &str, args: OpList) -> Result<Self::Lister> {
         self.log_start(Operation::List, &[("path", path)]);
         self.inner
diff --git a/core/layers/mime-guess/src/lib.rs b/core/layers/mime-guess/src/lib.rs
index 029ea2598..6c994fc89 100644
--- a/core/layers/mime-guess/src/lib.rs
+++ b/core/layers/mime-guess/src/lib.rs
@@ -176,6 +176,15 @@ impl Service for MimeGuessAccessor {
         self.0.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.0.restore(ctx, path, args).await
+    }
+
     fn delete(&self, ctx: &OperationContext) -> Result<Self::Deleter> {
         self.0.delete(ctx)
     }
diff --git a/core/layers/observe-metrics-common/src/lib.rs b/core/layers/observe-metrics-common/src/lib.rs
index 3ee72e400..c41a664dd 100644
--- a/core/layers/observe-metrics-common/src/lib.rs
+++ b/core/layers/observe-metrics-common/src/lib.rs
@@ -911,6 +911,41 @@ impl<I: MetricsIntercept> Service for MetricsAccessor<I> {
         res
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let labels = MetricLabels::new(self.info.clone(), Operation::Restore.into_static());
+        let start = Instant::now();
+
+        self.interceptor
+            .observe(labels.clone(), MetricValue::OperationExecuting(1));
+        let mut guard =
+            ExecutingGuard::new_operation(self.interceptor.clone(), labels.clone(), start);
+
+        let res = self
+            .inner
+            .restore(ctx, path, args)
+            .await
+            .inspect(|_| {
+                self.interceptor.observe(
+                    labels.clone(),
+                    MetricValue::OperationDurationSeconds(start.elapsed()),
+                );
+            })
+            .inspect_err(|err| {
+                self.interceptor.observe(
+                    labels.clone().with_error(err.kind()),
+                    MetricValue::OperationErrorsTotal,
+                );
+            });
+
+        guard.complete();
+        res
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let labels = MetricLabels::new(self.info.clone(), Operation::Stat.into_static());
 
diff --git a/core/layers/oteltrace/src/lib.rs b/core/layers/oteltrace/src/lib.rs
index d49f01a5a..8bddf1d5d 100644
--- a/core/layers/oteltrace/src/lib.rs
+++ b/core/layers/oteltrace/src/lib.rs
@@ -180,6 +180,20 @@ impl Service for OtelTraceService {
             .await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let tracer = global::tracer("opendal");
+        let mut span = tracer.start("restore");
+        span.set_attribute(KeyValue::new("path", path.to_string()));
+        span.set_attribute(KeyValue::new("args", format!("{args:?}")));
+        let cx = TraceContext::current_with_span(span);
+        self.inner.restore(ctx, path, args).with_context(cx).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let tracer = global::tracer("opendal");
         let mut span = tracer.start("stat");
diff --git a/core/layers/retry/src/lib.rs b/core/layers/retry/src/lib.rs
index 7371c83bf..32a39e18c 100644
--- a/core/layers/retry/src/lib.rs
+++ b/core/layers/retry/src/lib.rs
@@ -463,6 +463,29 @@ impl<I: RetryInterceptor> Service for RetryService<I> {
             .map_err(|err| err.set_persistent())
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let mut attempt: u32 = 0;
+        { || self.inner.restore(ctx, path, args.clone()) }
+            .retry(self.builder)
+            .when(|e| e.is_temporary())
+            .notify(|err, dur| {
+                attempt += 1;
+                self.notify.intercept(RetryEvent {
+                    op: Operation::Restore,
+                    err,
+                    retry_after: dur,
+                    attempt,
+                })
+            })
+            .await
+            .map_err(|err| err.set_persistent())
+    }
+
     fn list(&self, ctx: &OperationContext, path: &str, args: OpList) -> Result<Self::Lister> {
         let mut attempt: u32 = 0;
         let lister = { || self.inner.list(ctx, path, args.clone()) }
diff --git a/core/layers/route/src/lib.rs b/core/layers/route/src/lib.rs
index 64c762cd1..7d1c384a9 100644
--- a/core/layers/route/src/lib.rs
+++ b/core/layers/route/src/lib.rs
@@ -258,6 +258,18 @@ impl Service for RouteAccessor {
         }
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        match self.select(path) {
+            RouteSelected::Default(srv) => srv.restore(ctx, path, args).await,
+            RouteSelected::Target(target) => target.srv.restore(&target.ctx, path, args).await,
+        }
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         match self.select(path) {
             RouteSelected::Default(srv) => srv.stat(ctx, path, args).await,
diff --git a/core/layers/tail-cut/src/lib.rs b/core/layers/tail-cut/src/lib.rs
index e82490067..7524d1002 100644
--- a/core/layers/tail-cut/src/lib.rs
+++ b/core/layers/tail-cut/src/lib.rs
@@ -434,6 +434,15 @@ impl Service for TailCutService {
         .await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.with_deadline(Operation::Stat, None, self.inner.stat(ctx, path, args))
             .await
diff --git a/core/layers/throttle/src/lib.rs b/core/layers/throttle/src/lib.rs
index 02e502ac5..4bad39802 100644
--- a/core/layers/throttle/src/lib.rs
+++ b/core/layers/throttle/src/lib.rs
@@ -181,6 +181,15 @@ impl Service for ThrottleAccessor {
         self.inner.rename(ctx, from, to, args).await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.inner.restore(ctx, path, args).await
+    }
+
     fn list(&self, ctx: &OperationContext, path: &str, args: OpList) -> Result<Self::Lister> {
         self.inner.list(ctx, path, args)
     }
diff --git a/core/layers/timeout/src/lib.rs b/core/layers/timeout/src/lib.rs
index 86a04da0d..47f7f7f94 100644
--- a/core/layers/timeout/src/lib.rs
+++ b/core/layers/timeout/src/lib.rs
@@ -261,6 +261,16 @@ impl Service for TimeoutService {
             .await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        self.timeout(Operation::Restore, self.inner.restore(ctx, path, args))
+            .await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         self.timeout(Operation::Stat, self.inner.stat(ctx, path, args))
             .await
diff --git a/core/layers/tracing/src/lib.rs b/core/layers/tracing/src/lib.rs
index b1f4dbe8f..c4613d551 100644
--- a/core/layers/tracing/src/lib.rs
+++ b/core/layers/tracing/src/lib.rs
@@ -287,6 +287,16 @@ impl Service for TracingService {
             .await
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        let span = span!(Level::DEBUG, "restore", path, ?args);
+        self.inner.restore(ctx, path, args).instrument(span).await
+    }
+
     async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
         let span = span!(Level::DEBUG, "stat", path, ?args);
         self.inner.stat(ctx, path, args).instrument(span).await
diff --git a/core/services/s3/src/backend.rs b/core/services/s3/src/backend.rs
index 28c1ec012..50d14cd29 100644
--- a/core/services/s3/src/backend.rs
+++ b/core/services/s3/src/backend.rs
@@ -23,6 +23,7 @@ use std::sync::LazyLock;
 
 use base64::Engine;
 use base64::prelude::BASE64_STANDARD;
+use bytes::Buf;
 use http::StatusCode;
 use log::debug;
 use log::warn;
@@ -56,6 +57,7 @@ use crate::lister::S3ObjectVersionsLister;
 use crate::reader::*;
 use crate::writer::S3Writer;
 use crate::writer::S3Writers;
+use opendal_core::raw::oio::Copy;
 use opendal_core::raw::*;
 use opendal_core::*;
 
@@ -1121,6 +1123,10 @@ impl Builder for S3Builder {
                         Some(usize::MAX)
                     },
 
+                    restore: !is_s3_express,
+                    restore_with_version: !is_s3_express,
+                    restore_with_if_not_exists: !is_s3_express,
+
                     list: true,
                     list_with_limit: true,
                     list_with_start_after: !is_s3_express,
@@ -1307,6 +1313,82 @@ impl Service for S3Backend {
         ))
     }
 
+    async fn restore(
+        &self,
+        ctx: &OperationContext,
+        path: &str,
+        args: OpRestore,
+    ) -> Result<RpRestore> {
+        if let Some(version) = args.version() {
+            let copy_args = OpCopy::new()
+                .with_source_version(version)
+                .with_if_not_exists(args.if_not_exists());
+            let mut copier = new_s3_copier(
+                self.core.clone(),
+                ctx,
+                path,
+                path,
+                copy_args,
+                OpCopier::default(),
+            )?;
+
+            return match copier.close().await {
+                Ok(_) => Ok(RpRestore::new()),
+                Err(err) => {
+                    let _ = copier.abort().await;
+                    Err(err)
+                }
+            };
+        }
+
+        if args.if_not_exists() {
+            return Err(Error::new(
+                ErrorKind::ConfigInvalid,
+                "if_not_exists requires a restore version",
+            ));
+        }
+
+        let resp = self
+            .core
+            .s3_list_object_versions(ctx, path, "", Some(1), "", "")
+            .await?;
+        if resp.status() != StatusCode::OK {
+            return Err(parse_error(resp));
+        }
+
+        let output: ListObjectVersionsOutput =
+            quick_xml::de::from_reader(resp.into_body().reader())
+                .map_err(new_xml_deserialize_error)
+                .map_err(Error::set_temporary)?;
+        let abs_path = build_abs_path(&self.core.root, path);
+
+        if output
+            .version
+            .iter()
+            .any(|version| version.key == abs_path && version.is_latest)
+        {
+            return Ok(RpRestore::new());
+        }
+
+        let Some(marker) = output
+            .delete_marker
+            .into_iter()
+            .find(|marker| marker.key == abs_path && marker.is_latest)
+        else {
+            return Err(Error::new(
+                ErrorKind::NotFound,
+                "no live object or current delete marker exists",
+            ));
+        };
+
+        let delete_args = OpDelete::new().with_version(&marker.version_id);
+        let resp = self.core.s3_delete_object(ctx, path, &delete_args).await?;
+        match resp.status() {
+            StatusCode::NO_CONTENT | StatusCode::NOT_FOUND => Ok(RpRestore::new()),
+            _ => Err(parse_error(resp)),
+        }
+    }
+
     async fn presign(
         &self,
         ctx: &OperationContext,
@@ -1861,6 +1943,9 @@ mod tests {
         assert!(!capability.write_with_content_encoding);
         assert!(!capability.delete_with_version);
         assert!(!capability.copy_with_source_version);
+        assert!(!capability.restore);
+        assert!(!capability.restore_with_version);
+        assert!(!capability.restore_with_if_not_exists);
         assert!(!capability.list_with_start_after);
         assert!(!capability.list_with_recursive);
         assert!(!capability.list_with_versions);
diff --git a/core/services/s3/src/docs.md b/core/services/s3/src/docs.md
index 2968f2803..fdf1f60bd 100644
--- a/core/services/s3/src/docs.md
+++ b/core/services/s3/src/docs.md
@@ -9,12 +9,37 @@ Depending on its configuration and the backing system, this service can expose:
 - [x] delete
 - [x] list
 - [x] copy
+- [x] restore
 - [ ] rename
 - [x] presign
 
 Inspect the effective capability set with [`opendal_core::Operator::info`] and
 [`opendal_core::OperatorInfo::capability`] after building an operator.
 
+## Object restoration
+
+S3 restoration requires bucket versioning. [`opendal_core::Operator::restore`]
+removes the current delete marker. Calling it on an already-live object succeeds.
+It does not scan or remove older marker versions. If no live object or current
+delete marker exists, it returns [`opendal_core::ErrorKind::NotFound`].
+
+Use [`opendal_core::Operator::restore_with`] to promote a specific version:
+
+```rust,no_run
+# use opendal_core::Operator;
+# use opendal_core::Result;
+# async fn restore(op: Operator, version: &str) -> Result<()> {
+op.restore_with("path/to/file")
+    .version(version)
+    .await?;
+# Ok(())
+# }
+```
+
+Add `.if_not_exists(true)` when a selected version must not overwrite an
+object recreated by another writer. This condition requires an explicit
+version.
+
 ## Configuration
 
 Use [`crate::S3Config`] for serializable configuration and this builder's
diff --git a/core/tests/behavior/async_restore.rs b/core/tests/behavior/async_restore.rs
new file mode 100644
index 000000000..a8b4f88f5
--- /dev/null
+++ b/core/tests/behavior/async_restore.rs
@@ -0,0 +1,162 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use anyhow::Result;
+
+use crate::*;
+
+pub fn tests(op: &Operator, tests: &mut Vec<Trial>) {
+    let cap = op.info().capability();
+
+    if cap.restore && cap.read && cap.write && cap.delete {
+        tests.extend(async_trials!(
+            op,
+            test_restore_deleted_file,
+            test_restore_repeated_delete,
+            test_restore_live_file,
+            test_restore_not_found
+        ));
+    }
+
+    if cap.restore && cap.restore_with_version && cap.read && cap.write && cap.stat_with_version {
+        tests.extend(async_trials!(op, test_restore_with_version));
+    }
+
+    if cap.restore
+        && cap.restore_with_version
+        && cap.restore_with_if_not_exists
+        && cap.read
+        && cap.write
+        && cap.delete
+        && cap.stat_with_version
+    {
+        tests.extend(async_trials!(
+            op,
+            test_restore_with_if_not_exists,
+            test_restore_with_if_not_exists_conflict
+        ));
+    }
+}
+
+pub async fn test_restore_deleted_file(op: Operator) -> Result<()> {
+    let (path, content, _) = TEST_FIXTURE.new_file(op.clone());
+    op.write(&path, content.clone()).await?;
+    op.delete(&path).await?;
+
+    assert!(!op.exists(&path).await?);
+    op.restore(&path).await?;
+
+    assert_eq!(op.read(&path).await?.to_bytes(), content);
+    Ok(())
+}
+
+pub async fn test_restore_repeated_delete(op: Operator) -> Result<()> {
+    let (path, content, _) = TEST_FIXTURE.new_file(op.clone());
+    op.write(&path, content.clone()).await?;
+    op.delete(&path).await?;
+    op.delete(&path).await?;
+
+    op.restore(&path).await?;
+    op.restore(&path).await?;
+    assert_eq!(op.read(&path).await?.to_bytes(), content);
+    Ok(())
+}
+
+pub async fn test_restore_live_file(op: Operator) -> Result<()> {
+    let (path, content, _) = TEST_FIXTURE.new_file(op.clone());
+    op.write(&path, content.clone()).await?;
+
+    op.restore(&path).await?;
+
+    assert_eq!(op.read(&path).await?.to_bytes(), content);
+    Ok(())
+}
+
+pub async fn test_restore_not_found(op: Operator) -> Result<()> {
+    let path = uuid::Uuid::new_v4().to_string();
+    let err = op
+        .restore(&path)
+        .await
+        .expect_err("restoring an unknown path must fail");
+    assert_eq!(err.kind(), ErrorKind::NotFound);
+    Ok(())
+}
+
+pub async fn test_restore_with_version(op: Operator) -> Result<()> {
+    let (path, old_content, _) = TEST_FIXTURE.new_file(op.clone());
+    let (new_content, _) = gen_bytes(op.info().capability());
+    assert_ne!(old_content, new_content);
+
+    op.write(&path, old_content.clone()).await?;
+    let version = op
+        .stat(&path)
+        .await?
+        .version()
+        .expect("version must be present")
+        .to_string();
+    op.write(&path, new_content).await?;
+
+    op.restore_with(&path).version(version).await?;
+
+    assert_eq!(op.read(&path).await?.to_bytes(), old_content);
+    Ok(())
+}
+
+pub async fn test_restore_with_if_not_exists(op: Operator) -> Result<()> {
+    let (path, content, _) = TEST_FIXTURE.new_file(op.clone());
+    op.write(&path, content.clone()).await?;
+    let version = op
+        .stat(&path)
+        .await?
+        .version()
+        .expect("version must be present")
+        .to_string();
+    op.delete(&path).await?;
+
+    op.restore_with(&path)
+        .version(version)
+        .if_not_exists(true)
+        .await?;
+
+    assert_eq!(op.read(&path).await?.to_bytes(), content);
+    Ok(())
+}
+
+pub async fn test_restore_with_if_not_exists_conflict(op: Operator) -> Result<()> {
+    let (path, old_content, _) = TEST_FIXTURE.new_file(op.clone());
+    let (new_content, _) = gen_bytes(op.info().capability());
+    assert_ne!(old_content, new_content);
+
+    op.write(&path, old_content).await?;
+    let version = op
+        .stat(&path)
+        .await?
+        .version()
+        .expect("version must be present")
+        .to_string();
+    op.write(&path, new_content.clone()).await?;
+
+    let err = op
+        .restore_with(&path)
+        .version(version)
+        .if_not_exists(true)
+        .await
+        .expect_err("conditional restore must not overwrite a live path");
+    assert_eq!(err.kind(), ErrorKind::ConditionNotMatch);
+    assert_eq!(op.read(&path).await?.to_bytes(), new_content);
+    Ok(())
+}
diff --git a/core/tests/behavior/main.rs b/core/tests/behavior/main.rs
index 07ff1053e..9da0e3638 100644
--- a/core/tests/behavior/main.rs
+++ b/core/tests/behavior/main.rs
@@ -28,6 +28,7 @@ mod async_list;
 mod async_presign;
 mod async_read;
 mod async_rename;
+mod async_restore;
 mod async_stat;
 mod async_write;
 
@@ -61,6 +62,7 @@ fn main() -> anyhow::Result<()> {
     async_presign::tests(&op, &mut tests);
     async_read::tests(&op, &mut tests);
     async_rename::tests(&op, &mut tests);
+    async_restore::tests(&op, &mut tests);
     async_stat::tests(&op, &mut tests);
     async_write::tests(&op, &mut tests);