opendal 0.1.6.pre.rc.1-arm64-darwin-23

data/core/src/docs/comparisons/vs_object_store.md

@@ -0,0 +1,183 @@
+# OpenDAL vs object_store
+
+> NOTE: This document is written by OpenDAL's maintainers and not reviewed by
+> object_store's maintainers. So it could not be very objective.
+
+## About object_store
+
+[object_store](https://crates.io/crates/object_store) is
+
+> A focused, easy to use, idiomatic, high performance, `async` object store library interacting with object stores.
+
+It was initially developed for [InfluxDB IOx](https://github.com/influxdata/influxdb_iox/) and later split out and donated to [Apache Arrow](https://arrow.apache.org/).
+
+## Similarities
+
+### Language
+
+Yes, of course. Both `opendal` and `object_store` are developed in [Rust](https://www.rust-lang.org/), a language empowering everyone to build reliable and efficient software.
+
+### License
+
+Both `opendal` and `object_store` are licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+### Owner
+
+`object_store` is a part of `Apache Arrow` which means it's hosted and maintained by the [Apache Software Foundation](https://www.apache.org/).
+
+`opendal` is now hosted by the [Apache Software Foundation](https://www.apache.org/) also.
+
+### Domain
+
+Both `opendal` and `object_store` can be used to access data stored on object storage services. The primary users of those projects are both cloud-native databases too:
+
+- `opendal` is mainly used by:
+  - [databend](https://github.com/datafuselabs/databend): A modern Elasticity and Performance cloud data warehouse
+  - [GreptimeDB](https://github.com/GreptimeTeam/greptimedb): An open-source, cloud-native, distributed time-series database.
+  - [mozilla/sccache](https://github.com/mozilla/sccache/): sccache is ccache with cloud storage
+  - [risingwave](https://github.com/risingwavelabs/risingwave): A Distributed SQL Database for Stream Processing
+  - [Vector](https://github.com/vectordotdev/vector): A high-performance observability data pipeline.
+- `object_store` is mainly used by:
+  - [datafusion](https://github.com/apache/arrow-datafusion): Apache Arrow DataFusion SQL Query Engine
+  - [Influxdb IOx](https://github.com/influxdata/influxdb_iox/): The new core of InfluxDB is written in Rust on top of Apache Arrow.
+
+## Differences
+
+### Vision
+
+`opendal` is Open Data Access Layer that accesses data freely, painlessly, and efficiently. `object_store` is more focused on async object store support.
+
+You will see the different visions lead to very different routes.
+
+### Design
+
+`object_store` exposed a trait called [`ObjectStore`](https://docs.rs/object_store/latest/object_store/trait.ObjectStore.html) to users.
+
+Users need to build a `dyn ObjectStore` and operate on it directly:
+
+```rust
+let object_store: Arc<dyn ObjectStore> = Arc::new(get_object_store());
+let path: Path = "data/file01.parquet".try_into()?;
+let stream = object_store
+    .get(&path)
+    .await?
+    .into_stream();
+```
+
+`opendal` has a similar trait called [`Access`][crate::raw::Access]
+
+But `opendal` don't expose this trait to end users directly. Instead, `opendal` expose a new struct called [`Operator`][crate::Operator] and builds public API on it.
+
+```rust
+let op: Operator = Operator::from_env(Scheme::S3)?;
+let r = op.reader("data/file01.parquet").await?;
+```
+
+### Interception
+
+Both `object_store` and `opendal` provide a mechanism to intercept operations.
+
+`object_store` called `Adapters`:
+
+```rust
+let object_store = ThrottledStore::new(get_object_store(), ThrottleConfig::default())
+```
+
+`opendal` called [`Layer`](crate::raw::Layer):
+
+```rust
+let op = op.layer(TracingLayer).layer(MetricsLayer);
+```
+
+At the time of writing:
+
+object_store (`v0.5.0`) supports:
+
+- ThrottleStore: Rate Throttling
+- LimitStore: Concurrent Request Limit
+
+opendal supports:
+
+- ImmutableIndexLayer: immutable in-memory index.
+- LoggingLayer: logging.
+- MetadataCacheLayer: metadata cache.
+- ContentCacheLayer: content data cache.
+- MetricsLayer: metrics
+- RetryLayer: retry
+- SubdirLayer: Allow switch directory without changing original operator.
+- TracingLayer: tracing
+
+### Services
+
+`opendal` and `object_store` have different visions, so they have other services support:
+
+| service | opendal         | object_store                            |
+|---------|-----------------|-----------------------------------------|
+| azblob  | Y               | Y                                       |
+| fs      | Y               | Y                                       |
+| ftp     | Y               | N                                       |
+| gcs     | Y               | Y                                       |
+| hdfs    | Y               | Y *(via [datafusion-objectstore-hdfs])* |
+| http    | Y *(read only)* | N                                       |
+| ipfs    | Y *(read only)* | N                                       |
+| ipmfs   | Y               | N                                       |
+| memory  | Y               | Y                                       |
+| obs     | Y               | N                                       |
+| s3      | Y               | Y                                       |
+
+opendal has an idea called [`Capability`][crate::Capability], so it's services may have different capability sets. For example, opendal's `http` and `ipfs` are read only.
+
+### Features
+
+`opendal` and `object_store` have different visions, so they have different feature sets:
+
+| opendal   | object_store         | notes                                        |
+|-----------|----------------------|----------------------------------------------|
+| metadata  | -                    | get some metadata from underlying storage    |
+| create    | put                  | -                                            |
+| read      | get                  | -                                            |
+| read      | get_range            | -                                            |
+| -         | get_ranges           | opendal doesn't support read multiple ranges |
+| write     | put                  | -                                            |
+| stat      | head                 | -                                            |
+| delete    | delete               | -                                            |
+| -         | list                 | opendal doesn't support list with prefix     |
+| list      | list_with_delimiter  | -                                            |
+| -         | copy                 | -                                            |
+| -         | copy_if_not_exists   | -                                            |
+| -         | rename               | -                                            |
+| -         | rename_if_not_exists | -                                            |
+| presign   | -                    | get a presign URL of object                  |
+| multipart | multipart            | both support, but API is different           |
+| blocking  | -                    | opendal supports blocking API                |
+
+## Demo show
+
+The most straightforward complete demo how to read a file from s3:
+
+`opendal`
+
+```rust
+let mut builder = S3::default();
+builder.bucket("example");
+builder.access_key_id("access_key_id");
+builder.secret_access_key("secret_access_key");
+
+let store = Operator::new(builder)?.finish();
+let r = store.reader("data.parquet").await?;
+```
+
+`object_store`
+
+```rust
+let mut builder = AmazonS3Builder::new()
+.with_bucket_name("example")
+.with_access_key_id("access_key_id")
+.with_secret_access_key("secret_access_key");
+
+let store = Arc::new(builder.build()?);
+let path: Path = "data.parquet".try_into().unwrap();
+let stream = store.get(&path).await()?.into_stream();
+```
+
+[datafusion-objectstore-hdfs]: https://github.com/datafusion-contrib/datafusion-objectstore-hdfs/

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/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.