[incubator-opendal] branch remove_writer_copy_from created (now 38c099eb1)

[xu...@apache.org]

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

xuanwo pushed a change to branch remove_writer_copy_from
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git


      at 38c099eb1 fix

This branch includes the following new commits:

     new ed712e101 rfc: remove write copy from
     new 38c099eb1 fix

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[incubator-opendal] 02/02: fix

[xu...@apache.org]

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

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

commit 38c099eb1de5a6d5bee33d159522115ffc321f70
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Wed Sep 6 19:49:59 2023 +0800

    fix
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 .../{0000_remove_writer_copy_from.md => 0000_remove_write_copy_from.md} | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/src/docs/rfcs/0000_remove_writer_copy_from.md b/core/src/docs/rfcs/0000_remove_write_copy_from.md
similarity index 98%
rename from core/src/docs/rfcs/0000_remove_writer_copy_from.md
rename to core/src/docs/rfcs/0000_remove_write_copy_from.md
index 8e1d26e8c..98c846257 100644
--- a/core/src/docs/rfcs/0000_remove_writer_copy_from.md
+++ b/core/src/docs/rfcs/0000_remove_write_copy_from.md
@@ -1,4 +1,4 @@
-- Proposal Name: `remove_writer_copy_from`
+- Proposal Name: `remove_write_copy_from`
 - Start Date: 2023-09-06
 - RFC PR: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/pull/0000)
 - Tracking Issue: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000)

[incubator-opendal] 01/02: rfc: remove write copy from

[xu...@apache.org]

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

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

commit ed712e101e25ee2748cee93d743007665add02cc
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Wed Sep 6 19:49:22 2023 +0800

    rfc: remove write copy from
    
    Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
 core/src/docs/rfcs/0000_remove_writer_copy_from.md | 74 ++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/core/src/docs/rfcs/0000_remove_writer_copy_from.md b/core/src/docs/rfcs/0000_remove_writer_copy_from.md
new file mode 100644
index 000000000..8e1d26e8c
--- /dev/null
+++ b/core/src/docs/rfcs/0000_remove_writer_copy_from.md
@@ -0,0 +1,74 @@
+- Proposal Name: `remove_writer_copy_from`
+- Start Date: 2023-09-06
+- RFC PR: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/pull/0000)
+- Tracking Issue: [apache/incubator-opendal#0000](https://github.com/apache/incubator-opendal/issues/0000)
+
+# Summary
+
+Remove the `oio::Write::copy_from()` API pending a more thoughtful design.
+
+# Motivation
+
+In [RFC-2083: Writer Sink API](./2083_writer_sink_api.md), we launched an API, initially named `sink` and changed to `copy_from`, that enables data writing from a `Reader` to a `Writer` object.
+
+The current API signature is:
+
+```rust
+pub trait Write: Unpin + Send + Sync {
+    /// Copies data from the given reader to the writer.
+    ///
+    /// # Behavior
+    ///
+    /// - `Ok(n)` indicates successful writing of `n` bytes.
+    /// - `Err(err)` indicates a failure, resulting in zero bytes written.
+    ///
+    /// A situation where `n < size` may arise; the caller should then transmit the remaining bytes until the full amount is written.
+    async fn copy_from(&mut self, size: u64, src: oio::Reader) -> Result<u64>;
+}
+```
+
+The API has the following limitations:
+
+- Incompatibility with existing buffering and retry mechanisms.
+- Imposes ownership requirements on the reader, complicating its use. The reader must be recreated for every write operation.
+
+Due to restrictions in both Rust and Hyper's APIs, the following ideal implementation is currently unattainable:
+
+```rust
+pub trait Write: Unpin + Send + Sync {
+    async fn copy_from(&mut self, size: u64, src: &mut impl oio::Read) -> Result<u64>;
+}
+```
+
+- Rust doesn't allow us to have `impl oio::Read` in trait method if we want object safe.
+- hyper doesn't allow us to use reference here, it requires `impl Stream + 'static`.
+
+Given these constraints, the proposal is to remove `oio::Write::copy_from` until a more fitting design becomes feasible.
+
+# Guide-level explanation
+
+The `Writer::sink()` and `Writer::copy()` methods will be deprecated. As a substitute, users can utilize `AsyncWrite` to copy a file or stream. Additional helper functions like `Writer::copy_from(r: &dyn AsyncRead)` may be provided if necessary.
+
+# Reference-level explanation
+
+The method `oio::Write::copy_from` will be deprecated.
+
+# Drawbacks
+
+The deprecation eliminates the ability to stream data uploads. A viable alternative is to directly use `AsyncWrite` offered by `Writer`.
+
+# Rationale and Alternatives
+
+N/A
+
+# Prior Art
+
+N/A
+
+# Unresolved Questions
+
+N/A
+
+# Future Possibilities
+
+Introduce utility functions such as `Writer::copy_from(r: &dyn AsyncRead)` when possible.