tracking: implement restore for additional services

[Xuanwo]

Context

Operator::restore and the first S3 implementation landed in #8143. This issue turns the API discussion in #4321 into a service implementation tracker.

The checklist includes services whose providers expose versioning, delete markers, soft deletion, revisions, or a recycle bin. Other services should keep returning Unsupported until a provider-native recoverable state is identified.

Contract

Each implementation must preserve the public restore contract:

• restore(path) succeeds for a live object, restores the latest service-native deleted state, and returns NotFound when no live or recoverable state exists.
• restore_with(path).version(version) makes the selected historical version current.
• if_not_exists is advertised only when the provider offers an atomic destination condition.
• One restore call reverses one provider-native deletion state. For services that stack delete markers, repeated calls may expose progressively older states.
• Capabilities must reflect the configured provider and must not be inferred only from a compatible API shape.

Status

Completed

• S3 — feat(services/s3): support object restoration #8143 implements current delete-marker removal and version-selected server-side copy. S3 Express keeps restore capabilities disabled because it does not support versioning.

Version and delete-marker services

• COS — OpenDAL already exposes versioned stat/read/delete/list and deleted-entry listing (capabilities). Implement path restore by deleting the current delete marker, and selected-version restore with CopyObject's source versionId (COS API). Do not advertise conditional restore until an atomic versioned-destination condition is proven against COS.
• OSS — OpenDAL already exposes versioned stat/read/delete/list and deleted-entry listing (capabilities). OSS documents marker removal by version ID (delete markers) and source-version copy (CopyObject); implement base and selected-version restore.
• TOS — OpenDAL already exposes versioned stat/read/delete/list and deleted-entry listing (capabilities). Base restore can delete the current marker. Verify TOS's source-version CopyObject protocol against the actual service before advertising restore_with_version.
• OBS — OBS supports versioning, delete markers, and undelete (OBS User Guide, “Undeleting an Object”). OpenDAL does not yet expose OBS version list/read/delete/copy primitives, so add those prerequisites before restore.

Native soft-delete, revision, and recycle-bin services

• Azure Blob — Use Undelete Blob for soft-delete-only accounts (REST API). With blob versioning, discover a previous version and copy it to the base blob (versioning behavior). OpenDAL's copy request already accepts a source versionid (source). feat(services/azblob): implement "undelete" operation in azblob #7178 predates the current restore API and must be adapted before it can land.
• GCS — Restore a noncurrent generation by rewriting it to the live object (Object Versioning); restore a soft-deleted generation with objects.restore, including restoreToken when hierarchical namespace requires it (JSON API). OpenDAL rewrite already supports sourceGeneration and ifGenerationMatch=0 (source), but it still needs generation/deleted-state discovery.
• Backblaze B2 — Discover hide entries with b2_list_file_versions (API), remove the current hide marker with b2_delete_file_version, and promote a selected file ID with b2_copy_file (API). OpenDAL currently lacks the required version-listing capability.
• Dropbox — Discover a restorable revision and call files/restore(path, rev) (official SDK/API reference). OpenDAL currently does not expose Dropbox revisions, so define how revision IDs reach restore_with(...).version(...) and verify behavior against the service.
• Google Drive — OpenDAL delete already moves files to trash (source). Restore by finding the trashed item and setting trashed=false (Drive API guide). The implementation needs deleted-path-to-file-ID resolution and explicit destination-conflict semantics.
• OneDrive — Microsoft Graph supports restoring a recycle-bin item (driveItem restore) and promoting an older version (driveItemVersion restore). OpenDAL already lists versions but needs stable deleted-item ID resolution for path restore.

Investigation or blocked

• Aliyun Drive — Verify the exact consumer Alipan Open API used by OpenDAL. PDS recycle-bin documentation does not establish that this backend exposes the same restore endpoint or retention behavior.
• Yandex Disk — OpenDAL currently deletes with permanently=true (source). Restore is blocked until a separate decision changes or parameterizes delete semantics; restore work must not silently change existing delete behavior.

Pull request acceptance checklist

Every service PR should cover the applicable items:

• Advertise only capabilities verified for the configured provider.
• Succeed when the path is already live.
• Restore one recoverable deleted state.
• Return NotFound for an unknown or permanently deleted path.
• Promote the selected version when restore_with_version is advertised.
• Prove both success and conflict behavior against the actual service when restore_with_if_not_exists is advertised.
• Verify repeated deletion/restoration behavior when the provider stacks markers or revisions.
• Add actual-service behavior coverage and preset configuration.
• Document provider-specific prerequisites and limitations.

Provider documentation and request-construction analysis establish feasibility, but they do not replace actual-service behavior tests.

Non-goals

• Changing a service's existing delete semantics inside a restore PR.
• Downloading and re-uploading object data when the provider offers native server-side recovery or copy.
• Claiming recovery for unversioned, expired, or permanently deleted data.