opendal 0.1.6.pre.rc.1

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

@@ -0,0 +1,135 @@
+// 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 core concepts of OpenDAL's public API.
+//!
+//! OpenDAL provides a unified abstraction that helps developers access all storage services.
+//!
+//! There are two core concepts in OpenDAL:
+//!
+//! - [`Builder`]: Builder accepts a series of parameters to set up an instance of underlying services.
+//!   You can adjust the behaviour of underlying services with these parameters.
+//! - [`Operator`]: Developer can access underlying storage services with manipulating one Operator.
+//!   The Operator is a delegate for underlying implementation detail, and provides one unified access interface,
+//!   including `read`, `write`, `list` and so on.
+//!
+//! If you are interested in internal implementation details, please have a look at [`internals`][super::internals].
+//!
+//! # Builder
+//!
+//! Let's start with [`Builder`].
+//!
+//! A `Builder` is a trait that is implemented by the underlying services. We can use a `Builder` to configure and create a service.
+//! Developer can only create one service via Builder, in other words, Builder is the only public API provided by services.
+//! And other detailed implementation will be hidden.
+//!
+//! ```text
+//! ┌───────────┐                 ┌───────────┐
+//! │           │     build()     │           │
+//! │  Builder  ├────────────────►│  Service  │
+//! │           │                 │           │
+//! └───────────┘                 └───────────┘
+//! ```
+//!
+//! All [`Builder`] provided by OpenDAL is under [`services`][crate::services], we can refer to them like `opendal::services::S3`.
+//! By right the builder will be named like `OneServiceBuilder`, but usually we will export it to public with renaming it as one
+//! general name. For example, we will rename `S3Builder` to `S3` and developer will use `S3` finally.
+//!
+//! For example:
+//!
+//! ```no_run
+//! use opendal::services::S3;
+//!
+//! let mut builder = S3::default();
+//! builder.bucket("example");
+//! builder.root("/path/to/file");
+//! ```
+//!
+//! # Operator
+//! The [`Operator`] is a delegate for Service, the underlying implementation detail that implements [`Access`][crate::raw::Access],
+//! and it also provides one unified access interface.
+//! It will hold one reference of Service with its all generic types erased by OpenDAL,
+//! which is the reason why we say the Operator is the delegate of one Service.
+//!
+//! ```text
+//!                   ┌────────────────────┐
+//!                   │      Operator      │
+//!                   │         │delegate  │
+//! ┌─────────┐ build │         ▼          │ rely on ┌─────────────────────┐
+//! │ Builder ├───────┼──►┌────────────┐   │◄────────┤ business logic code │
+//! └─────────┘       │   │  Service   │   │         └─────────────────────┘
+//!                   └───┴────────────┴───┘
+//! ```
+//!
+//! `Operator` can be built from `Builder`:
+//!
+//! ```no_run
+//! # use opendal::Result;
+//! use opendal::services::S3;
+//! use opendal::Operator;
+//!
+//! # fn test() -> Result<()> {
+//! let mut builder = S3::default();
+//! builder.bucket("example");
+//! builder.root("/path/to/file");
+//!
+//! let op = Operator::new(builder)?.finish();
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! - `Operator` has it's internal `Arc`, so it's **cheap** to clone it.
+//! - `Operator` doesn't have generic parameters or lifetimes, so it's **easy** to use it everywhere.
+//! - `Operator` implements `Send` and `Sync`, so it's **safe** to send it between threads.
+//!
+//! After get an `Operator`, we can do operations on different paths.
+//!
+//!
+//! ```text
+//!                            ┌──────────────┐
+//!                  ┌────────►│ read("abc")  │
+//!                  │         └──────────────┘
+//! ┌───────────┐    │
+//! │ Operator  │    │         ┌──────────────┐
+//! │ ┌───────┐ ├────┼────────►│ write("def") │
+//! │ │Service│ │    │         └──────────────┘
+//! └─┴───────┴─┘    │
+//!                  │         ┌──────────────┐
+//!                  └────────►│ list("ghi/") │
+//!                            └──────────────┘
+//! ```
+//!
+//! We can read data with given path in this way:
+//!
+//! ```no_run
+//! # use opendal::Result;
+//! use opendal::services::S3;
+//! use opendal::Operator;
+//!
+//! # async fn test() -> Result<()> {
+//! let mut builder = S3::default();
+//! builder.bucket("example");
+//! builder.root("/path/to/file");
+//!
+//! let op = Operator::new(builder)?.finish();
+//! let bs: Vec<u8> = op.read("abc").await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! [`Builder`]: crate::Builder
+//! [`Operator`]: crate::Operator

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

@@ -0,0 +1,306 @@
+// 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 implementation details of [`Access`].
+//!
+//! [`Access`] is the core trait of OpenDAL's raw API. We operate
+//! underlying storage services via APIs provided by [`Access`].
+//!
+//! # Introduction
+//!
+//! [`Access`] can be split in the following parts:
+//!
+//! ```ignore
+//! //                  <----------Trait Bound-------------->
+//! pub trait Access: Send + Sync + Debug + Unpin + 'static {
+//!     type Reader: oio::Read;                    // --+
+//!     type Writer: oio::Write;                   //   +--> Associated Type
+//!     type Lister: oio::List;                    //   +
+//!     type Deleter: oio::Delete;                 // --+
+//!
+//!     // APIs
+//!     fn info(&self) -> Arc<AccessorInfo>;
+//!     fn create_dir(
+//!         &self,
+//!         path: &str,
+//!         args: OpCreateDir,
+//!     ) -> impl core::future::Future<Output = Result<RpCreateDir>> + MaybeSend;
+//! }
+//! ```
+//!
+//! Let's go deep into [`Access`] line by line.
+//!
+//! ## Trait Bound
+//!
+//! First we will read the declare of [`Access`] trait:
+//!
+//! ```ignore
+//! pub trait Access: Send + Sync + Debug + Unpin + 'static {}
+//! ```
+//!
+//! There are many trait boundings here. For now, [`Access`] requires the following bound:
+//!
+//! - [`Send`]: Allow user to send between threads without extra wrapper.
+//! - [`Sync`]: Allow user to sync between threads without extra lock.
+//! - [`Debug`][std::fmt::Debug]: Allow users to print underlying debug information of accessor.
+//! - [`Unpin`]: Make sure `Access` can be safely moved after being pinned, so users don't need to `Pin<Box<A>>`.
+//! - `'static`: Make sure `Access` is not a short-time reference, allow users to use `Access` in closures and futures without playing with lifetime.
+//!
+//! Implementer of `Access` should take care of the following things:
+//!
+//! - Implement `Debug` for backend, but don't leak credentials.
+//! - Make sure the backend is `Send` and `Sync`, wrap the internal struct with `Arc<Mutex<T>>` if necessary.
+//!
+//! ## Associated Type
+//!
+//! The first block of [`Access`] trait is our associated types. We
+//! require implementers to specify the type to be returned, thus avoiding
+//! the additional overhead of dynamic dispatch.
+//!
+//! [`Access`] has four associated types so far:
+//!
+//! - `Reader`: reader returned by `read` operation.
+//! - `Writer`: writer returned by `write` operation.
+//! - `Lister`: lister returned by `list` operation.
+//! - `Deleter`: deleter returned by `delete` operation.
+//!
+//! Implementer of `Access` should take care the following things:
+//!
+//! - OpenDAL will erase those type at the final stage of Operator building. Please don't return dynamic trait object like `oio::Reader`.
+//! - Use `()` as type if the operation is not supported.
+//!
+//! ## API Style
+//!
+//! Every API of [`Access`] follows the same style:
+//!
+//! - All APIs have a unique [`Operation`] and [`Capability`]
+//! - All APIs are orthogonal and do not overlap with each other
+//! - Most APIs accept `path` and `OpXxx`, and returns `RpXxx`.
+//! - Most APIs have `async` and `blocking` variants, they share the same semantics but may have different underlying implementations.
+//!
+//! [`Access`] can declare their capabilities via [`AccessorInfo`]'s `set_native_capability`:
+//!
+//! ```ignore
+//! impl Access for MyBackend {
+//!     fn info(&self) -> Arc<AccessorInfo> {
+//!         let am = AccessorInfo::default();
+//!         am.set_native_capability(
+//!             Capability {
+//!                 read: true,
+//!                 write: true,
+//!                 ..Default::default()
+//!         });
+//!
+//!         am.into()
+//!     }
+//! }
+//! ```
+//!
+//! Now that you have mastered [`Access`], let's go and implement our own backend!
+//!
+//! # Tutorial
+//!
+//! This tutorial implements a `duck` storage service that sends API
+//! requests to a super-powered duck. Gagaga!
+//!
+//! ## Scheme
+//!
+//! First of all, let's pick a good [`Scheme`] for our duck service. The
+//! scheme should be unique and easy to understand. Normally we should
+//! use its formal name.
+//!
+//! For example, we will use `s3` for AWS S3 Compatible Storage Service
+//! instead of `aws` or `awss3`. This is because there are many storage
+//! vendors that provide s3-like RESTful APIs, and our s3 service is
+//! implemented to support all of them, not just AWS S3.
+//!
+//! Obviously, we can use `duck` as scheme, let's add a new variant in [`Scheme`], and implement all required functions like `Scheme::from_str` and `Scheme::into_static`:
+//!
+//! ```ignore
+//! pub enum Scheme {
+//!     Duck,
+//! }
+//! ```
+//!
+//! ## Builder
+//!
+//! Then we can implement a builder for the duck service. The [`Builder`]
+//! will provide APIs for users to configure, and they will create an
+//! instance of a particular service.
+//!
+//! Let's create a `backend` mod under `services/duck` directory, and adding the following code.
+//!
+//! ```ignore
+//! use crate::raw::*;
+//! use crate::*;
+//!
+//! /// Duck Storage Service support. Gagaga!
+//! ///
+//! /// # Capabilities
+//! ///
+//! /// This service can be used to:
+//! ///
+//! /// - [x] read
+//! /// - [ ] write
+//! /// - [ ] list
+//! /// - [ ] presign
+//! ///
+//! /// # Configuration
+//! ///
+//! /// - `root`: Set the work dir for backend.
+//! ///
+//! /// ## Via Builder
+//! ///
+//! /// ```no_run
+//! /// use std::sync::Arc;
+//! ///
+//! /// use anyhow::Result;
+//! /// use opendal::services::Duck;
+//! /// use opendal::Operator;
+//! ///
+//! /// #[tokio::main]
+//! /// async fn main() -> Result<()> {
+//! ///     // Create Duck backend builder.
+//! ///     let mut builder = DuckBuilder::default();
+//! ///     // Set the root for duck, all operations will happen under this root.
+//! ///     //
+//! ///     // NOTE: the root must be absolute path.
+//! ///     builder.root("/path/to/dir");
+//! ///
+//! ///     let op: Operator = Operator::new(builder)?.finish();
+//! ///
+//! ///     Ok(())
+//! /// }
+//! /// ```
+//! #[derive(Default, Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+//! #[serde(default)]
+//! #[non_exhaustive]
+//! pub struct DuckConfig {
+//!     pub root: Option<String>,
+//! }
+//!
+//! #[derive(Default, Clone)]
+//! pub struct DuckBuilder {
+//!     config: DuckConfig,
+//! }
+//! ```
+//!
+//! Now let's implement the required APIs for `DuckConfig`:
+//!
+//! ```ignore
+//! impl Configurator for DuckConfig {
+//!     type Builder = DuckBuilder;
+//!
+//!     fn into_builder(self) -> Self::Builder {
+//!         DuckBuilder { config: self }
+//!     }
+//! }
+//! ```
+//!
+//! Note that `DuckBuilder` is part of our public API, so it needs to be
+//! documented. And any changes you make will directly affect users, so
+//! please take it seriously. Otherwise, you will be hunted down by many
+//! angry ducks.
+//!
+//! Then, we can implement required APIs for `DuckBuilder`:
+//!
+//! ```ignore
+//! impl DuckBuilder {
+//!     /// Set root of this backend.
+//!     ///
+//!     /// All operations will happen under this root.
+//!     pub fn root(&mut self, root: &str) -> &mut Self {
+//!         self.config.root = if root.is_empty() {
+//!             None
+//!         } else {
+//!             Some(root.to_string())
+//!         };
+//!
+//!         self
+//!     }
+//! }
+//!
+//! impl Builder for DuckBuilder {
+//!     type Config = DuckConfig;
+//!
+//!     fn build(self) -> Result<impl Access>  {
+//!         debug!("backend build started: {:?}", &self);
+//!
+//!         let root = normalize_root(&self.config.root.clone().unwrap_or_default());
+//!         debug!("backend use root {}", &root);
+//!
+//!         Ok(DuckBackend { root })
+//!     }
+//! }
+//! ```
+//!
+//! `DuckBuilder` is ready now, let's try to play with real ducks!
+//!
+//! ## Backend
+//!
+//! I'm sure you can see it already: `DuckBuilder` will build a
+//! `DuckBackend` that implements [`Access`]. The backend is what we used
+//! to communicate with the super-powered ducks!
+//!
+//! Let's keep adding more code under `backend.rs`:
+//!
+//! ```ignore
+//! /// Duck storage service backend
+//! #[derive(Clone, Debug)]
+//! pub struct DuckBackend {
+//!     root: String,
+//! }
+//!
+//! impl Access for DuckBackend {
+//!     type Reader = DuckReader;
+//!     type Writer = ();
+//!     type Lister = ();
+//!     type Deleter = ();
+//!
+//!     fn info(&self) -> Arc<AccessorInfo> {
+//!         let am = AccessorInfo::default();
+//!         am.set_scheme("duck")
+//!             .set_root(&self.root)
+//!             .set_native_capability(
+//!                 Capability {
+//!                     read: true,
+//!                     ..Default::default()
+//!             });
+//!
+//!         am.into()
+//!     }
+//!
+//!     async fn read(&self, path: &str, args: OpRead) -> Result<(RpRead, Self::Reader)> {
+//!         gagaga!()
+//!     }
+//! }
+//! ```
+//!
+//! Congratulations, we have implemented an [`Access`] that can talk to
+//! Super Power Ducks!
+//!
+//! What!? There are no Super Power Ducks? So sad, but never mind, we have
+//! really powerful storage services [here](https://github.com/apache/opendal/issues/5). Welcome to pick one to implement. I promise you won't
+//! have to `gagaga!()` this time.
+//!
+//! [`Access`]: crate::raw::Access
+//! [`Operation`]: crate::raw::Operation
+//! [`Capability`]: crate::Capability
+//! [`AccessorInfo`]: crate::raw::AccessorInfo
+//! [`Scheme`]: crate::Scheme
+//! [`Builder`]: crate::Builder
+//! [`Configurator`]: crate::Configurator

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

@@ -0,0 +1,42 @@
+// 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 implementation details of [`Layer`].
+//!
+//! [`Layer`] itself is quite simple:
+//!
+//! ```ignore
+//! pub trait Layer<A: Access> {
+//!     type LayeredAccess: Access;
+//!
+//!     fn layer(&self, inner: A) -> Self::LayeredAccess;
+//! }
+//! ```
+//!
+//! `XxxLayer` will wrap input [`Access`] as inner and return a new [`Access`]. So normally the implementation of [`Layer`] will be split into two parts:
+//!
+//! - `XxxLayer` will implement [`Layer`] and return `XxxAccessor` as `Self::LayeredAccess`.
+//! - `XxxAccess` will implement [`Access`] and be built by `XxxLayer`.
+//!
+//! Most layer only implements part of [`Access`], so we provide
+//! [`LayeredAccess`] which will forward all unimplemented methods to
+//! `inner`. It's highly recommend to implement [`LayeredAccess`] trait
+//! instead.
+//!
+//! [`Layer`]: crate::raw::Layer
+//! [`Access`]: crate::raw::Access
+//! [`LayeredAccess`]: crate::raw::LayeredAccess