meteorgan commented on code in PR #5556: URL: https://github.com/apache/opendal/pull/5556#discussion_r1918683978
########## core/src/docs/rfcs/5556_write_returns_metadata.md: ########## @@ -0,0 +1,119 @@ +- Proposal Name: `write_returns_metadata` +- Start Date: 2025-01-16 +- RFC PR: [apache/opendal#5556](https://github.com/apache/opendal/pull/5556) +- Tracking Issue: [apache/opendal#5557](https://github.com/apache/opendal/issues/5557) + +# Summary + +Enhance write operations by returning metadata after successful writes. + +# Motivation + +Currently, write operations (`write`, `write_with`, `writer`, `writer_with`) only return `Result<()>` or `Result<Writer>`. +Users who need metadata after writing (like `ETag` or `version_id`) must make an additional `stat()` call. This is inefficient +and can lead to race conditions if the file is modified between the write and stat operations. + +Many storage services (like S3, GCS, Azure Blob) return metadata in their write responses. We should expose this information +to users directly after write operations. + +# Guide-level explanation + +The write operations will be enhanced to return metadata: + +```rust +// Before +op.write("path/to/file", data).await?; +let meta = op.stat("path/to/file").await?; +if Some(etag) = meta.etag() { + println!("File ETag: {}", etag); +} + +// After +let meta = op.write("path/to/file", data).await?; +if Some(etag) = meta.etag() { + println!("File ETag: {}", etag); +} +``` + +For writer operations: + +```rust +// Before +let mut writer = op.writer("path/to/file").await?; +writer.write(data).await?; +writer.close().await?; +let meta = op.stat("path/to/file").await?; +if Some(etag) = meta.etag() { + println!("File ETag: {}", etag); +} + +// After +let mut writer = op.writer("path/to/file").await?; +writer.write(data).await?; +let meta = writer.close().await?; +if Some(etag) = meta.etag() { + println!("File ETag: {}", etag); +} +``` + +The behavior remains unchanged if users don't need the metadata - they can simply ignore the return value. + +# Reference-level explanation + +## Changes to `Operator` API + +The following functions will be modified to return `Result<Metadata>` instead of `Result<()>`: + +- `write()` +- `write_with()` + +The `writer()` and `writer_with()` return types remain unchanged as they return `Result<Writer>`. + +## Changes to struct `types::write::writer::Writer` + +The `Writer` struct will be modified to return `Result<Metadata>` instead of `Result<()>` for the `close()` function. + +## Changes to trait `oio::Write` and trait `oio::MultipartWrite` + +The `Write` trait will be modified to return `Result<Metadata>` instead of `Result<()>` for the `close()` function. + +The `MultipartWrite` trait will be modified to return `Result<Metadata>` instead of `Result<()>` for the `complete_part()` +and `write_once` function. + +## Implementation Details + +For services that return metadata in their write responses: +- The metadata will be captured from the service response +- All available fields (etag, version_id, etc.) will be populated + +For services that don't return metadata in write responses: +- A default metadata object will be returned Review Comment: Thank you for pointing this out. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
