opendal 0.1.6.pre.rc.1

data/core/src/docs/internals/mod.rs

@@ -0,0 +1,62 @@
+// 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.
+
+//! The internal implement details of OpenDAL.
+//!
+//! OpenDAL has provides unified abstraction via two-level API sets:
+//!
+//! - Public API like [`Operator`] provides user level API.
+//! - Raw API like [`Access`], [`Layer`] provides developer level API.
+//!
+//! OpenDAL tries it's best to keep the public API stable. But raw APIs
+//! may change between minor releases from time to time. So most users
+//! should only use the public API. And only developers need to implement
+//! with raw API to implement a new service [`Access`] or their own
+//! [`Layer`].
+//!
+//! In this section, we will talk about the following components:
+//!
+//! - [`Access`][accessor]: to connect underlying storage services.
+//! - [`Layer`][layer]: middleware/interceptor between storage services.
+//!
+//! The relation between [`Access`], [`Layer`] and [`Operator`] looks like the following:
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────────┬──────────┐
+//! │                                                 │          │
+//! │              ┌──────────┐  ┌────────┐           │          │
+//! │              │          │  │        ▼           │          │
+//! │      s3──┐   │          │  │ Tracing Layer      │          │
+//! │          │   │          │  │        │           │          │
+//! │     gcs──┤   │          │  │        ▼           │          │
+//! │          ├──►│ Accessor ├──┘ Metrics Layer ┌───►│ Operator │
+//! │  azblob──┤   │          │           │      │    │          │
+//! │          │   │          │           ▼      │    │          │
+//! │    hdfs──┘   │          │    Logging Layer │    │          │
+//! │              │          │           │      │    │          │
+//! │              └──────────┘           └──────┘    │          │
+//! │                                                 │          │
+//! └─────────────────────────────────────────────────┴──────────┘
+//! ```
+//!
+//! [`Builder`]: crate::Builder
+//! [`Operator`]: crate::Operator
+//! [`Access`]: crate::raw::Access
+//! [`Layer`]: crate::raw::Layer
+
+pub mod accessor;
+pub mod layer;

data/core/src/docs/mod.rs

@@ -0,0 +1,43 @@
+// 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.
+
+//! This module holds documentation for OpenDAL.
+//!
+//! It's highly recommended that you start by reading [`concepts`] first.
+
+#![allow(rustdoc::bare_urls)]
+
+pub mod comparisons;
+
+pub mod concepts;
+
+pub mod internals;
+
+pub mod performance;
+
+/// Changes log for all OpenDAL released versions.
+#[doc = include_str!("../../CHANGELOG.md")]
+#[cfg(not(doctest))]
+pub mod changelog {}
+
+#[cfg(not(doctest))]
+pub mod rfcs;
+
+/// Upgrade and migrate procedures while OpenDAL meets breaking changes.
+#[doc = include_str!("upgrade.md")]
+#[cfg(not(doctest))]
+pub mod upgrade {}

data/core/src/docs/performance/concurrent_write.md

@@ -0,0 +1,101 @@
+# Concurrent Write
+
+OpenDAL writes data sequentially by default.
+
+```rust
+# use opendal::Operator;
+# async fn test() {
+let w = op.writer("test.txt").await?;
+w.write(data1).await?;
+w.write(data2).await?;
+w.close().await?;
+# }
+```
+
+Most of the time, this can't maximize write performance due to limitations on a single connection. We can perform concurrent writes to improve performance.
+
+```rust
+# use opendal::Operator;
+# async fn test() {
+let w = op
+    .writer_with("test.txt")
+    .concurrent(8)
+    .await?;
+
+w.write(data1).await?;
+w.write(data2).await?;
+w.close().await?;
+# }
+```
+
+After setting `concurrent`, OpenDAL will attempt to write the specified file concurrently. The maximum level of concurrency is determined by the `concurrent` parameter. By default, it is set to 1, indicating a sequential write operation.
+
+Under the hood, OpenDAL maintains a task queue to manage concurrent writes. It spawns asynchronous tasks in the background using the [`Executor`][crate::Executor] and tracks the status of each task. The task queue is flushed when the writer is closed, allowing data to be written concurrently without blocking the main thread.
+
+Take our example here, the write of `data1` will not block the write of `data2`. The two writes will be executed concurrently.
+
+The underlying implementation of concurrent writes may vary depending on the backend. For instance, the `s3` backend leverages the S3 Multipart Uploads API to handle concurrent writes, while the `azblob` backend utilizes the Block API for the same purpose.
+
+## Tuning
+
+There are two parameters that can be tuned to optimize concurrent writes:
+
+- `concurrent`: This parameter controls the maximum number of concurrent writes. The default value is 1.
+- `chunk`: This parameter specifies the size of each chunk of data to be written. The default value is vary for different storage services.
+
+### `concurrent`
+
+The most important thing to understand is that `concurrent` is not a strict limit. It represents the maximum number of concurrent writes that OpenDAL will attempt to perform. The actual number of concurrent writes may be lower, depending on the input data throughput.
+
+For example, if you set `concurrent` to 8, OpenDAL will attempt to perform up to 8 concurrent writes. However, if the input data throughput is low, it might only carry out 2 or 3 concurrent writes at a time, as there isn't enough data to keep all 8 writes active.
+
+The best value for `concurrent` depends on the specific use case and the underlying storage service. In general, a higher value can lead to better performance, but it highly depends on the storage service and the network conditions. For example, if the storage service is robust and bandwidth is sufficient, you may observe a linear increase in performance with higher `concurrent` values. However, if the storage service has request limits or the network is nearly saturated, increasing `concurrent` may not lead to any performance improvement—and could even degrade performance due to infinite retries on errors.
+
+It's recommended to start with a lower value like `2` or `4` and gradually increase it while monitoring performance and resource usage.
+
+### `chunk`
+
+The `chunk` parameter specifies the size of each chunk of data to be written. A larger chunk size can improve performance, but it may also increase memory usage. The default value is vary for different storage services. 
+
+For example, s3 is using `5MiB` as the default chunk size. It's also the minimum chunk size for s3. If you set a smaller chunk size, OpenDAL will automatically adjust it to `5MiB`.
+
+The best value for `chunk` depends on the specific use case and the underlying storage service. For most object storage services, a chunk size of `8MiB` or larger is recommended. However, if you're working with smaller files or have limited memory resources, you may want to use a smaller chunk size.
+
+Please note that if you input small chunks of data, OpenDAL will attempt to merge them into a larger chunk before writing. This helps avoid the overhead of writing numerous small chunks, which can negatively affect performance.
+
+## Usage
+
+To upload a large in-memory chunk concurrently:
+
+```rust
+# use opendal::Operator;
+# async fn test() {
+let data = vec![0; 10 * 1024 * 1024]; // 10MiB
+let _ = op.write_with("test.txt", data).concurrent(4).await?;
+# }
+```
+
+`concurrent` and `chunk` also works in [`into_sink`][crate::Writer::into_sink], [`into_bytes_sink`][crate::Writer::into_bytes_sink] and [`into_futures_async_write`][crate::Writer::into_futures_async_write]:
+
+```rust
+use std::io;
+
+use bytes::Bytes;
+use futures::SinkExt;
+use opendal::{Buffer, Operator};
+use opendal::Result;
+
+async fn test(op: Operator) -> io::Result<()> {
+    let mut w = op
+        .writer_with("hello.txt")
+        .concurrent(8)
+        .chunk(256)
+        .await?
+        .into_sink();
+    let bs = "Hello, World!".as_bytes();
+    w.send(Buffer::from(bs)).await?;
+    w.close().await?;
+
+    Ok(())
+}
+```

data/core/src/docs/performance/http_optimization.md

@@ -0,0 +1,124 @@
+# HTTP Optimization
+
+All OpenDAL HTTP-based storage services use the same [HttpClient][crate::raw::HttpClient] abstraction. This design offers users a unified interface for configuring HTTP clients. The default HTTP client is [reqwest](https://crates.io/crates/reqwest), a popular and widely used HTTP client library in Rust.
+
+Many of the services supported by OpenDAL are HTTP-based. This guide aims to provide optimization tips for using HTTP-based storage services. While these tips are also applicable to other HTTP clients, the configuration methods may vary.
+
+Please note that the following optimizations are based on experience and may not be suitable for all scenarios. The most effective way to determine the optimal configuration is to test it in your specific environment.
+
+## HTTP/1.1
+
+According to benchmarks from OpenDAL users, `HTTP/1.1` is generally faster than `HTTP/2` for large-scale download and upload operations.
+
+`reqwest` tends to maintain only a single TCP connection for `HTTP/2`, relying on its built-in multiplexing capabilities. While this works well for small files, such as web page downloads, the design is not ideal for handling large files or massive file scan OLAP workloads.
+
+When `HTTP/2` is disabled, `reqwest` falls back to `HTTP/1.1` and utilizes its default connection pool. This approach is better suited for large files, as it allows multiple TCP connections to be opened and used concurrently, significantly improving performance for large file downloads and uploads.
+
+If your workloads involve large files or require high throughput, and are not sensitive to latency, consider disabling `HTTP/2` in your configuration.
+
+```rust
+let client = reqwest::ClientBuilder::new()
+  // Disable http2 for better performance.
+  .http1_only()
+  .build()
+  .expect("http client must be created");
+
+// Update the http client in the operator.
+let op = op.update_http_client(|_| HttpClient::with(client));
+```
+
+## DNS Caching
+
+`reqwest` uses the DNS resolver provided by Rust's standard library by default, which is backed by the `getaddrinfo` system call under the hood. This system call does not cache results by default, meaning that each time you make a request to a new domain, a DNS lookup will be performed.
+
+Under high-throughput workloads, this can cause a significant performance degradation, as each request incurs the overhead of a DNS lookup. It can also negatively affect the resolver, potentially overwhelming it with the volume of requests. In extreme cases, this may result in a DoS attack on the resolver, rendering it unresponsive.
+
+To mitigate this issue, you can enable DNS caching in `reqwest` by using the `hickory-dns` feature. This feature provides a more efficient DNS resolver that caches results.
+
+```rust
+let client = reqwest::ClientBuilder::new()
+  // Enable hickory dns for dns caching and async dns resolve.
+  .hickory_dns(true)
+  .build()
+  .expect("http client must be created");
+
+// Update the http client in the operator.
+let op = op.update_http_client(|_| HttpClient::with(client));
+```
+
+The default DNS cache settings from `hickory_dns` are generally sufficient for most workloads. However, if you have specific requirements—such as sharing the same DNS cache across multiple HTTP clients or configuring the DNS cache size—you can use the `Xuanwo/reqwest-hickory-resolver` crate to set up a custom DNS resolver.
+
+```rust
+/// Global shared hickory resolver.
+static GLOBAL_HICKORY_RESOLVER: LazyLock<Arc<HickoryResolver>> = LazyLock::new(|| {
+    let mut opts = ResolverOpts::default();
+    // Only query for the ipv4 address.
+    opts.ip_strategy = LookupIpStrategy::Ipv4Only;
+    // Use larger cache size for better performance.
+    opts.cache_size = 1024;
+    // Positive TTL is set to 5 minutes.
+    opts.positive_min_ttl = Some(Duration::from_secs(300));
+    // Negative TTL is set to 1 minute.
+    opts.negative_min_ttl = Some(Duration::from_secs(60));
+
+    Arc::new(
+        HickoryResolver::default()
+            // Always shuffle the DNS results for better performance.
+            .with_shuffle(true)
+            .with_options(opts),
+    )
+});
+
+let client = reqwest::ClientBuilder::new()
+  // Use our global hickory resolver instead.
+  .dns_resolver(GLOBAL_HICKORY_RESOLVER.clone())
+  .build()
+  .expect("http client must be created");
+
+// Update the http client in the operator.
+let op = op.update_http_client(|_| HttpClient::with(client));
+```
+
+The `ResolverOpts` has many options that can be configured. For a complete list of options, please refer to the [hickory_resolver documentation](https://docs.rs/hickory-resolver/latest/hickory_resolver/config/struct.ResolverOpts.html).
+
+Here is a summary of the most commonly used options:
+
+- `ip_strategy`: `hickory_resolver` default to use `Ipv4thenIpv6` strategy, which means it will first query for the IPv4 address and then the IPv6 address. This is generally a good strategy for most workloads. However, if you only need IPv4 addresses, you can set this option to `Ipv4Only` to avoid unnecessary DNS lookups.
+- `cache_size`: This option controls the size of the DNS cache. A larger cache size can improve performance, but it may also increase memory usage. The default value is `32`.
+- `positive_min_ttl` and `negative_min_ttl`: This option controls the minimum TTL for positive and negative DNS responses. A longer TTL can improve performance, but it may also increase the risk of stale DNS records. The default value is `None`. Some bad DNS servers may return a TTL of `0` even when the record is valid. In this case, you can set a longer TTL to avoid unnecessary DNS lookups.
+
+In addition to the options mentioned above, `Xuanwo/reqwest-hickory-resolver` also offers a `shuffle` option. This setting determines whether the DNS results are shuffled before being returned. Shuffling can enhance performance by distributing the load more evenly across multiple IP addresses.
+
+## Timeout
+
+`reqwest` didn't set a default timeout for HTTP requests. This means that if a request hangs or takes too long to complete, it can block the entire process, leading to performance degradation or even application crashes.
+
+It's recommended to set a connect timeout for HTTP requests to prevent this issue. 
+
+```rust
+let client = reqwest::ClientBuilder::new()
+  // Set a connect timeout of 5 seconds.
+  .connect_timeout(Duration::from_secs(5))
+  .build()
+  .expect("http client must be created");
+
+// Update the http client in the operator.
+let op = op.update_http_client(|_| HttpClient::with(client));
+```
+
+It's also recommended to use opendal's [`TimeoutLayer`][crate::layers::TimeoutLayer] to prevent slow requests hangs forever. This layer will automatically cancel the request if it takes too long to complete.
+
+```rust
+let op = op.layer(TimeoutLayer::new());
+```
+
+## Connection Pool
+
+`reqwest` uses a connection pool to manage HTTP connections. This allows multiple requests to share the same connection, reducing the overhead of establishing new connections for each request.
+
+By default, the connection pool is unlimited, allowing `reqwest` to open as many connections as needed. The default keep-alive timeout is 90 seconds, meaning any connection idle for longer than that will be closed.
+
+You can tune those settings via:
+
+- [pool_idle_timeout](https://docs.rs/reqwest/0.12.15/reqwest/struct.ClientBuilder.html#method.pool_idle_timeout): Set an optional timeout for idle sockets being kept-alive.
+- [pool_max_idle_per_host](https://docs.rs/reqwest/0.12.15/reqwest/struct.ClientBuilder.html#method.pool_max_idle_per_host): Sets the maximum idle connection per host allowed in the pool.

data/core/src/docs/performance/mod.rs

@@ -0,0 +1,32 @@
+// 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.
+
+//! OpenDAL Performance Guide
+//!
+//! OpenDAL is designed in a zero-cost abstraction way, which means that
+//! users won't pay for the abstraction cost if they don't use it. But this
+//! can also means that users can't maximize the performance of OpenDAL
+//! if they don't know how to use it.
+//!
+//! This document will introduce some tips to improve the performance of
+//! OpenDAL.
+
+#[doc = include_str!("concurrent_write.md")]
+pub mod concurrent_write {}
+
+#[doc = include_str!("http_optimization.md")]
+pub mod http_optimization {}

data/core/src/docs/rfcs/0000_example.md

@@ -0,0 +1,74 @@
+- Proposal Name: (fill me in with a unique ident, `my_awesome_feature`)
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- RFC PR: [apache/opendal#0000](https://github.com/apache/opendal/pull/0000)
+- Tracking Issue: [apache/opendal#0000](https://github.com/apache/opendal/issues/0000)
+
+# Summary
+
+One paragraph explanation of the proposal.
+
+# Motivation
+
+Why are we doing this? What use cases does it support? What is the expected outcome?
+
+# Guide-level explanation
+
+Explain the proposal as if it was already included in the opendal and you were teaching it to other opendal users. That generally means:
+
+- Introducing new named concepts.
+- Explaining the feature mainly in terms of examples.
+- Explaining how opendal users should *think* about the feature and how it should impact the way they use opendal. It should explain the impact as concretely as possible.
+- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
+- If applicable, describe the differences between teaching this to exist opendal users and new opendal users.
+
+# Reference-level explanation
+
+This is the technical portion of the RFC. Explain the design in sufficient detail that:
+
+- Its interaction with other features is clear.
+- It is reasonably clear how the feature would be implemented.
+- Corner cases are dissected by example.
+
+The section should return to the examples given in the previous section and explain more fully how the detailed proposal makes those examples work.
+
+# Drawbacks
+
+Why should we *not* do this?
+
+# Rationale and alternatives
+
+- Why is this design the best in the space of possible designs?
+- What other designs have been considered, and what is the rationale for not choosing them?
+- What is the impact of not doing this?
+
+# Prior art
+
+Discuss prior art, both the good and the bad, in relation to this proposal.
+A few examples of what this can include are:
+
+- What lessons can we learn from what other communities have done here?
+
+This section is intended to encourage you as an author to think about the lessons from other communities provide readers of your RFC with a fuller picture.
+If there is no prior art, that is fine - your ideas are interesting to us, whether they are brand new or an adaptation from other projects.
+
+# Unresolved questions
+
+- What parts of the design do you expect to resolve through the RFC process before this gets merged?
+- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?
+
+# Future possibilities
+
+Think about what the natural extension and evolution of your proposal would be and how it would affect the opendal. Try to use this section as a tool to more fully consider all possible interactions with the project in your proposal.
+
+Also, consider how this all fits into the roadmap for the project.
+
+This is also a good place to "dump ideas", if they are out of scope for the
+RFC, you are writing but otherwise related.
+
+If you have tried and cannot think of any future possibilities,
+you may state that you cannot think of anything.
+
+Note that having something written down in the future-possibilities section
+is not a reason to accept the current or a future RFC; such notes should be
+in the section on motivation or rationale in this or subsequent RFCs.
+The section merely provides additional information.

data/core/src/docs/rfcs/0000_foyer_integration.md

@@ -0,0 +1,111 @@
+- Proposal Name: `foyer_integration`
+- Start Date: 2025-07-07
+- RFC PR: [apache/opendal#6370](https://github.com/apache/opendal/pull/6370)
+- Tracking Issue: [apache/opendal#6372](https://github.com/apache/opendal/issues/6372)
+
+# Summary
+
+Integrate [*foyer*](https://github.com/foyer-rs/foyer) hybrid support into OpenDAL for performance boost and cost reduction.
+
+# Motivation
+
+Object storage is the most commonly used option by OpenDAL users. In cloud-based Object Storage services like AWS S3 / GCS, the distribution of request latency is often one to several orders of magnitude higher than local disks or memory, and these services are often billed based on the number of requests. 
+
+Applications based on these cloud object storage services often need to introduce caching to optimize storage performance while reducing request overhead. *Foyer* provides a mixed caching capability of memory and disk, offering a better balance between performance and cost, thus becoming a dependency for many systems based on cloud object storage along with OpenDAL. e.g. RisingWave, SlateDB, etc.
+
+However, regardless of which cache component is introduced, users need to operate additional cache-related APIs apart from operating OpenDAL. If *foyer* can be integrated as an optional component into OpenDAL, it can provide users with a more friendly, convenient, and transparent interaction method.
+
+By introducing *foyer* integration, the users will be benefited in to following aspects:
+
+- Performance boost and cost reduction by caching with both memory and disk.
+- A completely transparent implementation, using the same operation APIs as before.
+
+[RFC#6297](https://github.com/apache/opendal/pull/6297) has mentioned a general cache layer design, and *foyer* can be integrated into OpenDAL as a general cache in this way. However, this may not fully leverage *foyer*'s capabilities:
+
+- *Foyer* support automatic cache refilling on cache miss. The behavior differs based on the reason of cache miss and the statistics of the entry (e.g. entry not in cache, disk operation throttled, age of entry, etc). All of the abilities are supported by a non-standard API `fetch()`, which other cache libraries don't have.
+- *Foyer* support requests deduplication on the same key. *Foyer* ensures that for concurrent access to the same key, only one request will actually access the disk cache or remote storage, while other requests will wait for this request to return and directly reuse the result, in order to minimize overhead as much as possible.
+
+These capabilities overlap with some of the functionalities provided by a general cache Layer, while others are orthogonal. An independent *foyer* integration (e.g. `FoyerLayer`) can fully leverage Foyer's capabilities. At the same time, this will not affect future integration with Foyer and other cache libraries through the general cache layer.
+
+# Guide-level explanation
+
+## 1. Enable feature
+
+```toml
+opendal = { version = "*", features = ["layers-foyer"] }
+```
+
+## 2. Build foyer instance
+
+```rust
+let cache = HybridCacheBuilder::new()
+    .memory(10)
+    .with_shards(1)
+    .storage(Engine::Large(LargeEngineOptions::new()))
+    .with_device_options(
+        DirectFsDeviceOptions::new(dir.path())
+            .with_capacity(16 * MiB as usize)
+            .with_file_size(1 * MiB as usize),
+    )
+    .with_recover_mode(RecoverMode::None)
+    .build()
+    .await
+    .unwrap();
+```
+
+## 3. Build OpenDAL operator with foyer layer
+
+```rust
+let op = Operator::new(Dashmap::default())
+    .unwrap()
+    .layer(FoyerLayer::new(cache.clone()))
+    .finish();
+```
+
+## 4. Perform operations as you used to
+
+```rust
+op.write("obj-1").await.unwrap();
+
+assert_eq!(op.list("/").await.unwrap().len(), 1);
+
+op.read("obj-1").await.unwrap();
+
+op.delete("obj-1").await.unwrap();
+
+assert!(op.list("/").await.unwrap().is_empty());
+```
+
+# Reference-level explanation
+
+As mentioned in the previous section, this RFC aims to integrate *foyer* to fully leverage its capabilities, rather than designing a generic cache layer. Therefore, a transparent integration can be achieved through a `FoyerLayer`.
+
+`FoyerLayer` holds both the reference of both internal accessor, and a *foyer* instance. For operations supported by *foyer* and compatible in behavior, the `FoyerLayer` will use *foyer* to handle requests, accessing the internal accessor as needed. For operations that *foyer* cannot support, it will automatically fallback to using the internal accessor implementation.
+
+Here are the details of operations that involve *foyer* operation:
+
+- `read`: Read from *foyer* hybrid cache, if the hybrid cache misses, fallback to internal accessor `read` operation.
+    - For range get, *foyer* caches and fetches the whole object and returns the requested object range. (In future versions, it may be possible to support user configuration for whether to cache the entire object or only the objects covered by the range.)
+- `write`: Insert hybrid cache on internal accessor `write` operation success.
+- `delete`: Delete object from *foyer* hybrid cache regardless of internal accessor `delete` operation success.
+
+# Drawbacks
+
+Since we cannot perceive whether other users have updated the data in the underlying storage system, introducing a cache in this case may lead to data inconsistency. Therefore, the integration of Foyer is more suitable for object storage systems that do not support updating objects.
+
+# Rationale and alternatives
+
+[RFC#6297](https://github.com/apache/opendal/pull/6297) has mentioned a general cache layer design, but cannot fully leverage *foyer*'s capabilities. However, the two are not in conflict.  At the same time, because #6297 has not yet been finalized, I prefer to implement a layer specifically for the *foyer* first. This does not affect the future implementation of a general cache layer and can also help quickly identify potential user needs and issues.
+
+# Prior art
+
+*Foyer* has already been applied in systems like RisingWave, ChromaDB, and SlateDB. We can learn from this experience. Notably, both RisingWave and SlateDB support using OpenDAL as the data access layer. This RFC will provide a smoother experience for users with similar needs.
+
+# Unresolved questions
+
+None
+
+# Future possibilities
+
+- Based on the experience of implementing the *foyer* layer, a more general cache layer can be developed.
+- Adjust the API of *foyer* to align with the usage of OpenDAL, enhancing compatibility between the two.