RFC: rename if not exists by hfutatzhanghb · Pull Request #7818 · apache/opendal

hfutatzhanghb · 2026-06-24T04:52:59Z

Which issue does this PR close?

N/A.

Rationale for this change

OpenDAL needs a documented cross-service contract for conditional rename before
extending the public API. The design must align with existing write and copy
options while preserving the atomic destination condition.

What changes are included in this PR?

Propose rename_with(...).if_not_exists(true) and RenameOptions.
Define AlreadyExists and Unsupported behavior.
Define the atomic no-replace capability requirement.
Analyze HDFS, FS, S3, and other service implementation boundaries.

Are there any user-facing changes?

No implementation is included in this RFC PR. If accepted, the proposed public
API and capability will be implemented separately.

AI Usage Statement

AI assistance (GPT-5.5 with Codex) was used to prepare this RFC.
Reviewed by GLM-5.2 with Codex

hfutatzhanghb · 2026-06-24T07:38:25Z

@Xuanwo @erickguan Hi， could you please help review this RFC PR when free? Thanks very much!

erickguan

Good writing. I added some comments. I also have questions on atomicity.

You will also need Xuanwo's approval :)

erickguan · 2026-06-24T12:27:09Z

+
+### Multi-step overwrite services
+
+`aliyun_drive`, `gdrive`, `goosefs`, and `koofr` currently delete or trash an


Depending on if we are changing rename to be atomic, say yes. Then we are essentially making these services' rename to be a simulation. Either this is way beyond the scope and we register this problem as a future work. Or we would see a way to address this problem in this RFC. e.g., a capability flag for declaring so? or documentation on atomicity with/without rename_with_if_not_exists.

I think the answer is neither — this RFC does NOT propose making rename atomic. Multi-step delete+rename is a valid implementation of overwrite, not a "simulation." It genuinely fulfills the contract: the destination ends up with the source content.

The atomicity gate is introduced only for rename_with_if_not_exists because it adds a conditional check that would be meaningless without atomic enforcement. Overwrite rename (the default) has no such check, so no new atomicity requirement.

That said, a capability flag like rename_is_atomic for the base rename operation is a reasonable idea, but it is separate from this RFC. I would prefer keeping this RFC scoped to if_not_exists and filing a follow-up issue for rename atomicity documentation/capability if the maintainers agree it is worth tracking.

@hfutatzhanghb Is zhb your handle on OpenDAL discord?

Co-authored-by: Erick Guan <297343+erickguan@users.noreply.github.com>

hfutatzhanghb

@hfutatzhanghb

Address erickguan's review: explicitly document that RenameOptions is always constructable, matching the existing write and copy pattern where the correctness_check layer returns Unsupported when the capability is not advertised.

Replace ambiguous 'the destination condition' with explicit phrasing: 'destination-does-not-exist check' and 'destination already exists (if_not_exists condition fails)'. Addresses erickguan's review feedback.

Replace the ambiguous 'the operation' with 'the rename' for clarity. Addresses erickguan's review feedback.

Add an explicit paragraph explaining that overwrite rename does not require atomicity (multi-step delete+rename achieves the same result), while the if_not_exists condition must be checked atomically with the move. A backend with non-atomic overwrite may still support conditional rename by skipping the pre-delete and relying on the native conflict rejection. HDFS is the example. Addresses erickguan's review feedback about the apparent contradiction between non-atomic overwrite implementations and the atomicity requirement for conditional rename.

erickguan · 2026-06-24T13:50:45Z

This RFC will require a tracking issue once approved :)

hfutatzhanghb · 2026-06-24T13:55:59Z

Should i create an issue and update rfc now？

…

---- Replied Message ---- | From | Erick ***@***.***> | | Date | 06/24/2026 21:51 | | To | ***@***.***> | | Cc | ***@***.***>***@***.***> | | Subject | Re: [apache/opendal] RFC: rename if not exists (PR #7818) | erickguan left a comment (apache/opendal#7818) This RFC will require a tracking issue once approved :) — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

erickguan · 2026-06-24T14:05:08Z

@hfutatzhanghb Up to you. I would suggest waiting Xuanwo's review.

hfutatzhanghb · 2026-06-24T14:06:43Z

Got it!

…

---- Replied Message ---- | From | Erick ***@***.***> | | Date | 06/24/2026 22:05 | | To | ***@***.***> | | Cc | ***@***.***>***@***.***> | | Subject | Re: [apache/opendal] RFC: rename if not exists (PR #7818) | erickguan left a comment (apache/opendal#7818) @hfutatzhanghb Up to you. I would suggest waiting Xuanwo's review. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

hfutatzhanghb · 2026-06-25T02:48:11Z

Hi, @Xuanwo please cc when have free time. Thanks very much!

Xuanwo

LGTM, thank you @hfutatzhanghb for working on this and thank you @erickguan for the review!

docs(core): propose rename if not exists RFC

3702bec

hfutatzhanghb requested a review from Xuanwo as a code owner June 24, 2026 04:53

dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. releases-note/docs The PR modifies docs related content or has a title that begins with "docs" labels Jun 24, 2026

docs(core): assign RFC 7818

3ba03e7

hfutatzhanghb mentioned this pull request Jun 24, 2026

feat(core): add conditional rename option #7815

Open

zhanghaobo@kanzhun.com added 2 commits June 24, 2026 13:05

docs(core): expand conditional rename service analysis

db1bd5f

docs(core): remove placeholder tracking issue

4575406

hfutatzhanghb force-pushed the codex/rfc-rename-if-not-exists branch from dfdbf69 to 4575406 Compare June 24, 2026 07:01

erickguan reviewed Jun 24, 2026

View reviewed changes

hfutatzhanghb and others added 4 commits June 24, 2026 20:35

Update core/core/src/docs/rfcs/7818_rename_if_not_exists.md

6d2a098

Co-authored-by: Erick Guan <297343+erickguan@users.noreply.github.com>

Update core/core/src/docs/rfcs/7818_rename_if_not_exists.md

02c395f

Co-authored-by: Erick Guan <297343+erickguan@users.noreply.github.com>

Update core/core/src/docs/rfcs/7818_rename_if_not_exists.md

094516f

Co-authored-by: Erick Guan <297343+erickguan@users.noreply.github.com>

Update core/core/src/docs/rfcs/7818_rename_if_not_exists.md

c68c6c9

Co-authored-by: Erick Guan <297343+erickguan@users.noreply.github.com>

hfutatzhanghb commented Jun 24, 2026

View reviewed changes

zhanghaobo@kanzhun.com added 4 commits June 24, 2026 21:04

docs(core): clarify 'the destination condition' terminology

3b1d557

Replace ambiguous 'the destination condition' with explicit phrasing: 'destination-does-not-exist check' and 'destination already exists (if_not_exists condition fails)'. Addresses erickguan's review feedback.

docs(core): clarify 'the operation' -> 'the rename' in atomicity section

e5e68c0

Replace the ambiguous 'the operation' with 'the rename' for clarity. Addresses erickguan's review feedback.

Xuanwo approved these changes Jun 25, 2026

View reviewed changes

dosubot Bot added the lgtm This PR has been approved by a maintainer label Jun 25, 2026

Xuanwo merged commit 5ebfb5b into apache:main Jun 25, 2026
103 checks passed

hfutatzhanghb deleted the codex/rfc-rename-if-not-exists branch June 25, 2026 07:46


		### Multi-step overwrite services

		`aliyun_drive`, `gdrive`, `goosefs`, and `koofr` currently delete or trash an

Uh oh!

Conversation

hfutatzhanghb commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue does this PR close?

Rationale for this change

What changes are included in this PR?

Are there any user-facing changes?

AI Usage Statement

Uh oh!

hfutatzhanghb commented Jun 24, 2026

Uh oh!

erickguan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

erickguan Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

hfutatzhanghb Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

erickguan Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

hfutatzhanghb left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erickguan commented Jun 24, 2026

Uh oh!

hfutatzhanghb commented Jun 24, 2026 via email

Uh oh!

erickguan commented Jun 24, 2026

Uh oh!

hfutatzhanghb commented Jun 24, 2026 via email

Uh oh!

hfutatzhanghb commented Jun 25, 2026

Uh oh!

Xuanwo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hfutatzhanghb commented Jun 24, 2026 •

edited

Loading

hfutatzhanghb left a comment •

edited

Loading