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

data/core/README.md

@@ -0,0 +1,228 @@
+# Apache OpenDAL™ Rust Core: One Layer, All Storage.
+
+[![Build Status]][actions] [![Latest Version]][crates.io] [![Crate Downloads]][crates.io] [![chat]][discord]
+
+[build status]: https://img.shields.io/github/actions/workflow/status/apache/opendal/ci_core.yml?branch=main
+[actions]: https://github.com/apache/opendal/actions?query=branch%3Amain
+[latest version]: https://img.shields.io/crates/v/opendal.svg
+[crates.io]: https://crates.io/crates/opendal
+[crate downloads]: https://img.shields.io/crates/d/opendal.svg
+[chat]: https://img.shields.io/discord/1081052318650339399
+[discord]: https://opendal.apache.org/discord
+
+Apache OpenDAL™ is an Open Data Access Layer that enables seamless interaction with diverse storage services.
+
+<img src="https://opendal.apache.org/img/architectural.png" alt="OpenDAL Architectural" width="61.8%" />
+
+## Useful Links
+
+- Documentation: [release](https://docs.rs/opendal/) | [dev](https://opendal.apache.org/docs/rust/opendal/)
+- [Examples](./examples)
+- [Release Notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html)
+- [Upgrade Guide](https://docs.rs/opendal/latest/opendal/docs/upgrade/index.html)
+- [RFC List](https://docs.rs/opendal/latest/opendal/docs/rfcs/index.html)
+
+## Services
+
+OpenDAL supports the following storage [services](https://docs.rs/opendal/latest/opendal/services/index.html):
+
+| Type                           | Services                                                                                                                                 | 
+|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| 
+| Standard Storage Protocols     | ftp http [sftp] [webdav]                                                                                                                 |
+| Object Storage Services        | [azblob] [cos] [gcs] [obs] [oss] [s3] <br> [b2] [openstack_swift] [upyun] [vercel_blob]                                                  |
+| File Storage Services          | fs [alluxio] [azdls] [azfile] [compfs] <br> [dbfs] [gridfs] [hdfs] [hdfs_native] [ipfs] [webhdfs]                                        |
+| Consumer Cloud Storage Service | [aliyun_drive] [gdrive] [onedrive] [dropbox] [koofr] <br> [pcloud] [seafile] [yandex_disk]                                      |
+| Key-Value Storage Services     | [cacache] [cloudflare_kv] [dashmap] memory [etcd] <br> [foundationdb] [persy] [redis] [rocksdb] [sled] <br> [redb] [tikv] |
+| Database Storage Services      | [d1] [mongodb] [mysql] [postgresql] [sqlite] [surrealdb]                                                                                 |
+| Cache Storage Services         | [ghac] [memcached] [mini_moka] [moka] [vercel_artifacts]                                                                                 |
+| Git Based Storage Services     | [huggingface]                                                                                                                            |
+
+[sftp]: https://datatracker.ietf.org/doc/html/draft-ietf-secsh-filexfer-02
+[webdav]: https://datatracker.ietf.org/doc/html/rfc4918
+
+[azblob]: https://azure.microsoft.com/en-us/services/storage/blobs/
+[cos]: https://www.tencentcloud.com/products/cos
+[gcs]: https://cloud.google.com/storage
+[obs]: https://www.huaweicloud.com/intl/en-us/product/obs.html
+[oss]: https://www.aliyun.com/product/oss
+[s3]: https://aws.amazon.com/s3/
+[b2]: https://www.backblaze.com/
+[openstack_swift]: https://docs.openstack.org/swift/latest/
+[upyun]: https://www.upyun.com/
+[vercel_blob]: https://vercel.com/docs/storage/vercel-blob
+
+[alluxio]: https://docs.alluxio.io/os/user/stable/en/api/REST-API.html
+[azdls]: https://azure.microsoft.com/en-us/products/storage/data-lake-storage/
+[azfile]: https://learn.microsoft.com/en-us/rest/api/storageservices/file-service-rest-api
+[compfs]: https://github.com/compio-rs/compio/
+[dbfs]: https://docs.databricks.com/en/dbfs/index.html
+[gridfs]: https://www.mongodb.com/docs/manual/core/gridfs/
+[hdfs]: https://hadoop.apache.org/docs/r3.3.4/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html
+[hdfs_native]: https://github.com/Kimahriman/hdfs-native
+[ipfs]: https://ipfs.tech/
+[webhdfs]: https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/WebHDFS.html
+
+[aliyun_drive]: https://www.aliyundrive.com/
+[gdrive]: https://www.google.com/drive/
+[onedrive]: https://www.microsoft.com/en-us/microsoft-365/onedrive/online-cloud-storage
+[dropbox]: https://www.dropbox.com/
+[koofr]: https://koofr.eu/
+[pcloud]: https://www.pcloud.com/
+[seafile]: https://www.seafile.com/
+[yandex_disk]: https://360.yandex.com/disk/
+
+[cacache]: https://crates.io/crates/cacache
+[cloudflare_kv]: https://developers.cloudflare.com/kv/
+[dashmap]: https://github.com/xacrimon/dashmap
+[etcd]: https://etcd.io/
+[foundationdb]: https://www.foundationdb.org/
+[persy]: https://crates.io/crates/persy
+[redis]: https://redis.io/
+[rocksdb]: http://rocksdb.org/
+[sled]: https://crates.io/crates/sled
+[redb]: https://crates.io/crates/redb
+[tikv]: https://tikv.org/
+
+[d1]: https://developers.cloudflare.com/d1/
+[mongodb]: https://www.mongodb.com/
+[mysql]: https://www.mysql.com/
+[postgresql]: https://www.postgresql.org/
+[sqlite]: https://www.sqlite.org/
+[surrealdb]: https://surrealdb.com/
+
+[ghac]: https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows
+[memcached]: https://memcached.org/
+[mini_moka]: https://github.com/moka-rs/mini-moka
+[moka]: https://github.com/moka-rs/moka
+[vercel_artifacts]: https://vercel.com/docs/concepts/monorepos/remote-caching
+
+[huggingface]: https://huggingface.co/
+
+## Layers
+
+OpenDAL supports the following storage [layers](https://docs.rs/opendal/latest/opendal/layers/index.html) to extend the behavior:
+
+| Name                      | Depends                  | Description                                                                           |
+|---------------------------|--------------------------|---------------------------------------------------------------------------------------|
+| [`AsyncBacktraceLayer`]   | [async-backtrace]        | Add Efficient, logical 'stack' traces of async functions for the underlying services. |
+| [`AwaitTreeLayer`]        | [await-tree]             | Add a Instrument await-tree for actor-based applications to the underlying services.  |
+| [`BlockingLayer`]         | [tokio]                  | Add blocking API support for non-blocking services.                                   |
+| [`ChaosLayer`]            | [rand]                   | Inject chaos into underlying services for robustness test.                            |
+| [`ConcurrentLimitLayer`]  | [tokio]                  | Add concurrent request limit.                                                         |
+| [`DtraceLayer`]           | [probe]                  | Support User Statically-Defined Tracing(aka USDT) on Linux                            |
+| [`LoggingLayer`]          | [log]                    | Add log for every operations.                                                         |
+| [`MetricsLayer`]          | [metrics]                | Add metrics for every operations.                                                     |
+| [`MimeGuessLayer`]        | [mime_guess]             | Add `Content-Type` automatically based on the file extension in the operation path.   |
+| [`FastraceLayer`]         | [fastrace]               | Add fastrace for every operations.                                                    |
+| [`OtelMetricsLayer`]      | [opentelemetry::metrics] | Add opentelemetry::metrics for every operations.                                      |
+| [`OtelTraceLayer`]        | [opentelemetry::trace]   | Add opentelemetry::trace for every operations.                                        |
+| [`PrometheusClientLayer`] | [prometheus_client]      | Add prometheus metrics for every operations.                                          |
+| [`PrometheusLayer`]       | [prometheus]             | Add prometheus metrics for every operations.                                          | 
+| [`RetryLayer`]            | [backon]                 | Add retry for temporary failed operations.                                            |
+| [`ThrottleLayer`]         | [governor]               | Add a bandwidth rate limiter to the underlying services.                              |
+| [`TimeoutLayer`]          | [tokio]                  | Add timeout for every operations to avoid slow or unexpected hang operations.         |
+| [`TracingLayer`]          | [tracing]                | Add tracing for every operations.                                                     |
+
+[`AsyncBacktraceLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.AsyncBacktraceLayer.html
+[async-backtrace]: https://github.com/tokio-rs/async-backtrace
+[`AwaitTreeLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.AwaitTreeLayer.html
+[await-tree]: https://github.com/risingwavelabs/await-tree
+[`BlockingLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.BlockingLayer.html
+[tokio]: https://github.com/tokio-rs/tokio
+[`ChaosLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.ChaosLayer.html
+[rand]: https://github.com/rust-random/rand
+[`ConcurrentLimitLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.ConcurrentLimitLayer.html
+[`DtraceLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.DtraceLayer.html
+[probe]: https://github.com/cuviper/probe-rs
+[`LoggingLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.LoggingLayer.html
+[log]: https://github.com/rust-lang/log
+[`MetricsLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.MetricsLayer.html
+[metrics]: https://github.com/metrics-rs/metrics
+[`MimeGuessLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.MimeGuessLayer.html
+[mime_guess]: https://github.com/abonander/mime_guess
+[`FastraceLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.FastraceLayer.html
+[fastrace]: https://github.com/fastracelabs/fastrace
+[`OtelMetricsLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.OtelMetricsLayer.html
+[`OtelTraceLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.OtelTraceLayer.html
+[opentelemetry::trace]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/index.html
+[`PrometheusClientLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.PrometheusClientLayer.html
+[prometheus_client]: https://github.com/prometheus/client_rust
+[`PrometheusLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.PrometheusLayer.html
+[prometheus]: https://github.com/tikv/rust-prometheus
+[`RetryLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.RetryLayer.html
+[backon]: https://github.com/Xuanwo/backon
+[`ThrottleLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.ThrottleLayer.html
+[governor]: https://github.com/boinkor-net/governor
+[`TimeoutLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.TimeoutLayer.html
+[`TracingLayer`]: https://docs.rs/opendal/latest/opendal/layers/struct.TracingLayer.html
+[tracing]: https://github.com/tokio-rs/tracing
+
+## Quickstart
+
+```rust
+use opendal::Result;
+use opendal::layers::LoggingLayer;
+use opendal::services;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Pick a builder and configure it.
+    let mut builder = services::S3::default();
+    builder.bucket("test");
+
+    // Init an operator
+    let op = Operator::new(builder)?
+        // Init with logging layer enabled.
+        .layer(LoggingLayer::default())
+        .finish();
+
+    // Write data
+    op.write("hello.txt", "Hello, World!").await?;
+
+    // Read data
+    let bs = op.read("hello.txt").await?;
+
+    // Fetch metadata
+    let meta = op.stat("hello.txt").await?;
+    let mode = meta.mode();
+    let length = meta.content_length();
+
+    // Delete
+    op.delete("hello.txt").await?;
+
+    Ok(())
+}
+```
+
+## Examples
+
+| Name                | Description                                                   |
+|---------------------|---------------------------------------------------------------|
+| [Basic]             | Show how to use opendal to operate storage service.           |
+| [Concurrent Upload] | Show how to perform upload concurrently to a storage service. |
+| [Multipart Upload]  | Show how to perform a multipart upload to a storage service.  |
+
+[Basic]: ./examples/basic
+[Concurrent Upload]: ./examples/concurrent-upload
+[Multipart Upload]: ./examples/multipart-upload
+
+## Contributing
+
+Check out the [CONTRIBUTING](./CONTRIBUTING.md) guide for more details on getting started with contributing to this project.
+
+## Used by
+
+Check out the [users](./users.md) list for more details on who is using OpenDAL.
+
+## Branding
+
+The first and most prominent mentions must use the full form: **Apache OpenDAL™** of the name for any individual usage (webpage, handout, slides, etc.) Depending on the context and writing style, you should use the full form of the name sufficiently often to ensure that readers clearly understand the association of both the OpenDAL project and the OpenDAL software product to the ASF as the parent organization.
+
+For more details, see the [Apache Product Name Usage Guide](https://www.apache.org/foundation/marks/guide).
+
+## License and Trademarks
+
+Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+
+Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.

data/core/benches/README.md

@@ -0,0 +1,18 @@
+# OpenDAL Benchmarks
+
+Running benchmark
+
+```shell
+OPENDAL_TEST=memory cargo bench
+```
+
+Build flamegraph:
+
+```shell
+cargo flamegraph --bench io -- seek --bench
+```
+
+- `--bench io` pick the `io` target.
+- `-- seek --bench`: chose the benches with `seek` and `--bench` is required by `criterion`
+
+After `flamegraph.svg` has been generated, use browser to visit it.

data/core/benches/ops/README.md

@@ -0,0 +1,26 @@
+# Ops Benchmark Tests
+
+Ops Benchmark Tests measure every operation's performance on the target platform.
+
+To support benching different backends simultaneously, we use `environment value` to carry the backend config.
+
+## Setup
+
+Please copy `.env.example` to `.env` and change the values on need.
+
+Take `fs` for example, we add config on `fs` on `/tmp`.
+
+```dotenv
+OPENDAL_FS_ROOT=/tmp
+```
+
+Notice: The default will skip benches if the env is not set.
+
+## Run
+
+Test specific backend, take s3 for example, first set the corresponding environment variables of s3, then:
+
+```shell
+OPENDAL_TEST=s3
+cargo bench ops --features tests
+```

data/core/benches/types/README.md

@@ -0,0 +1,9 @@
+# Types Benchmark Tests
+
+This benchmark contains performance testing of critical data structures in opendal types, currently including performance testing of Buffer.
+
+## Run
+
+```shell
+cargo bench types --features tests
+```

data/core/benches/vs_fs/README.md

@@ -0,0 +1,35 @@
+# OpenDAL Benchmark VS Fs
+
+This benchmark compares the performance of OpenDAL with the performance of the `std::fs`.
+
+## Goal
+
+We expect OpenDAL to match `std::fs` in speed: the throughput of OpenDAL should be within a `5%` range of `std::fs`.
+
+## Usage
+
+For test: `cargo run`
+
+```shell
+Testing vs_fs/std_fs_read
+Success
+Testing vs_fs/opendal_fs_read
+Success
+Testing vs_fs/opendal_fs_read_with_range
+Success
+```
+
+For bench: `cargo run --release -- --bench`
+
+```shell
+read/std_fs       time:   [749.57 µs 762.69 µs 777.07 µs]
+                  thrpt:  [20.108 GiB/s 20.487 GiB/s 20.845 GiB/s]
+                        
+read/opendal_fs   time:   [750.90 µs 755.39 µs 760.49 µs]
+                  thrpt:  [20.546 GiB/s 20.685 GiB/s 20.808 GiB/s]
+                        
+read/opendal_fs_with_range
+                  time:   [684.02 µs 690.77 µs 697.99 µs]
+                  thrpt:  [22.386 GiB/s 22.620 GiB/s 22.843 GiB/s]
+
+```

data/core/benches/vs_s3/README.md

@@ -0,0 +1,55 @@
+# OpenDAL Benchmark VS AWS SDK S3
+
+This benchmark compares the performance of OpenDAL with the performance of the `aws_sdk_s3`.
+
+## Goal
+
+We expect OpenDAL to match `aws_sdk_s3` in speed: the throughput of OpenDAL should be within a `5%` range of `aws_sdk_s3`.
+
+## Notes
+
+Please run bench case separately, otherwise the result will be affected by each other since we are sharing the same runtime.
+
+## Usage
+
+For test: `cargo run`
+
+```shell
+> cargo run
+Testing read/opendal_s3_reader
+Success
+Testing read/aws_s3_sdk_into_async_read
+Success
+Testing read/opendal_s3_reader_with_capacity
+Success
+Testing read/aws_s3_sdk_into_async_read_with_capacity
+Success
+```
+
+For bench case: `cargo run --release -- opendal_s3_reader --bench`
+
+```shell
+> cargo run --release -- opendal_s3_reader --bench
+read/opendal_s3_reader  time:   [12.773 ms 13.004 ms 13.232 ms]
+                        thrpt:  [1.1809 GiB/s 1.2016 GiB/s 1.2232 GiB/s]
+```
+
+For bench: `cargo run --release -- --bench`
+
+```shell
+> cargo run --release -- --bench
+read/opendal_s3_reader  time:   [12.773 ms 13.004 ms 13.232 ms]
+                        thrpt:  [1.1809 GiB/s 1.2016 GiB/s 1.2232 GiB/s]
+
+read/aws_s3_sdk_into_async_read
+                        time:   [12.527 ms 12.842 ms 13.158 ms]
+                        thrpt:  [1.1875 GiB/s 1.2168 GiB/s 1.2473 GiB/s]
+
+read/opendal_s3_reader_with_capacity
+                        time:   [9.6098 ms 9.8133 ms 10.017 ms]
+                        thrpt:  [1.5599 GiB/s 1.5922 GiB/s 1.6259 GiB/s]
+
+read/aws_s3_sdk_into_async_read_with_capacity
+                        time:   [9.8970 ms 10.113 ms 10.329 ms]
+                        thrpt:  [1.5128 GiB/s 1.5451 GiB/s 1.5788 GiB/s]
+```

data/core/edge/README.md

@@ -0,0 +1,3 @@
+# OpenDAL Edge Tests
+
+OpenDAL edge tests served as edge tests for the OpenDAL project. They will have pre-set data and will test the functionality of the OpenDAL project.

data/core/edge/file_write_on_full_disk/README.md

@@ -0,0 +1,14 @@
+# File Write on Fill Disk
+
+Reported by [The `FsBackend` only writes partial bytes and doesn't raise any errors](https://github.com/apache/opendal/issues/3052).
+
+Setup:
+
+```shell
+fallocate -l 512K disk.img 
+mkfs disk.img 
+mkdir ./td
+sudo mount -o loop td.img ./td
+chmod a+wr ./td
+```
+

data/core/edge/s3_aws_assume_role_with_web_identity/README.md

@@ -0,0 +1,18 @@
+# S3 AWS Assume Role With Web Identity
+
+This edge test case is for AWS s3 services that authed by `Assume Role With Web Identity`.
+
+For setup, please configure bucket and OIDC correctly, for example:
+
+```yaml
+- uses: actions/github-script@v7
+  id: id-token
+  with:
+    script: return await core.getIDToken("sts.amazonaws.com")
+    result-encoding: string
+- name: Write ID token to file
+  run: echo "${{ steps.id-token.outputs.result }}" > core/tests/data/web_identity_token
+```
+
+And configure `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN`.
+

data/core/edge/s3_read_on_wasm/.gitignore

@@ -0,0 +1,3 @@
+pkg/
+node_modules/
+dist/

data/core/edge/s3_read_on_wasm/README.md

@@ -0,0 +1,42 @@
+# S3 Read on WASM
+
+This test is used to ensure opendal can run on WASM target.
+
+## Setup
+
+Start the S3 server at `http://127.0.0.1:9900`
+
+We are using the following config values, please feel free to change based on your own needs.
+
+```rust
+let mut cfg = S3::default();
+cfg.endpoint("http://127.0.0.1:9900");
+cfg.access_key_id("minioadmin");
+cfg.secret_access_key("minioadmin");
+cfg.bucket("opendal");
+cfg.region("us-east-1");
+```
+
+## Install
+
+```shell
+cargo install wasm-pack
+```
+
+## Build
+
+```shell
+wasm-pack build
+```
+
+## Test
+
+NOTE: 
+
+- You need to have Chrome installed.
+- We can't run on node.js yet.
+- We can't run on headless chrome yet.
+
+```shell
+wasm-pack test --chrome
+```

data/core/edge/s3_read_on_wasm/webdriver.json

@@ -0,0 +1,15 @@
+{
+  "moz:firefoxOptions": {
+    "prefs": {
+      "media.navigator.streams.fake": true,
+      "media.navigator.permission.disabled": true
+    },
+    "args": []
+  },
+  "goog:chromeOptions": {
+    "args": [
+      "--use-fake-device-for-media-stream",
+      "--use-fake-ui-for-media-stream"
+    ]
+  }
+}

data/core/examples/README.md

@@ -0,0 +1,23 @@
+# Apache OpenDAL™ Rust Core Examples
+
+Thank you for using OpenDAL!
+
+Those examples are designed to help you to understand how to use OpenDAL Rust Core.
+
+## Setup
+
+All examples following the same setup steps:
+
+To run this example, please copy the `.env.example`, which is at project root, to `.env` and change the values on need.
+
+Take `fs` for example, we need to change to enable behavior test on `fs` on `/tmp`.
+
+```dotenv
+OPENDAL_FS_ROOT=/path/to/dir
+```
+
+into
+
+```dotenv
+OPENDAL_FS_ROOT=/tmp/
+```

data/core/examples/basic/README.md

@@ -0,0 +1,15 @@
+# Basic
+
+This example will show how to use opendal to operate storage service.
+
+## Setup
+
+Refer [Setup](../README.md) to setup all examples.
+
+## Run
+
+Use `OPENDAL_TEST` to control which service to run example:
+
+```shell
+OPENDAL_TEST=fs cargo run
+```

data/core/examples/concurrent-upload/README.md

@@ -0,0 +1,15 @@
+# Concurrent Upload
+
+This example will show how to perform upload concurrently to a storage service.
+
+## Setup
+
+Refer [Setup](../README.md) to setup all examples.
+
+## Run
+
+Use `OPENDAL_TEST` to control which service to run example:
+
+```shell
+OPENDAL_TEST=s3 cargo run
+```

data/core/examples/multipart-upload/README.md

@@ -0,0 +1,15 @@
+# Multipart Upload
+
+This example will show how to perform a multipart upload to a storage service.
+
+## Setup
+
+Refer [Setup](../README.md) to setup all examples.
+
+## Run
+
+Use `OPENDAL_TEST` to control which service to run example:
+
+```shell
+OPENDAL_TEST=s3 cargo run
+```

data/core/fuzz/.gitignore

@@ -0,0 +1,5 @@
+target
+corpus
+artifacts
+coverage
+tmp

data/core/fuzz/README.md

@@ -0,0 +1,68 @@
+# Fuzz Test for OpenDAL
+
+fuzz test are used to test the robustness of the code. 
+
+## Setup
+
+
+
+To run the fuzz tests, please copy the `.env.example`, which is at project root, to `.env` and change the values on need.
+
+Take `fs` for example, we need to change to enable fuzz test on `fs` on `/tmp`.
+
+```dotenv
+OPENDAL_TEST=fs
+OPENDAL_FS_ROOT=/path/to/dir/
+```
+
+into
+
+```dotenv
+OPENDAL_TEST=fs
+OPENDAL_FS_ROOT=/tmp/
+```
+
+
+## Run
+
+List all fuzz targets.
+
+```bash
+cargo +nightly fuzz list
+```
+
+Build fuzz targets.
+
+```bash
+cargo +nightly fuzz build
+```
+
+Run a fuzz target(such as `reader`).
+
+```bash
+cargo +nightly fuzz run fuzz_reader
+```
+
+## Crash Reproduction
+
+If you want to reproduce a crash, you first need to obtain the Base64 encoded code, which usually appears at the end of a crash report, and store it in a file.
+
+Alternatively, if you already have the crash file, you can skip this step.
+
+```bash
+echo "Base64" > .crash
+```
+
+Print the `std::fmt::Debug` output for an input.
+
+```bash
+cargo +nightly fuzz fmt fuzz_target .crash
+```
+
+Rerun the fuzz test with the input.
+
+```bash
+cargo +nightly fuzz run fuzz_target .crash
+```
+
+For more details, please visit [cargo fuzz](https://rust-fuzz.github.io/book/cargo-fuzz/tutorial.html) or run the command cargo fuzz --help.